llama-stack-mirror/docs/docs/api-experimental/describe-an-agent-by-its-id.api.mdx

---
id: describe-an-agent-by-its-id
title: "Describe an agent by its ID."
description: "Describe an agent by its ID."
sidebar_label: "Describe an agent by its ID."
hide_title: true
hide_table_of_contents: true
api: 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
sidebar_class_name: "get api-method"
info_path: docs/api-experimental/llama-stack-specification-experimental-apis
custom_edit_url: null
---

import MethodEndpoint from "@theme/ApiExplorer/MethodEndpoint";
import ParamsDetails from "@theme/ParamsDetails";
import RequestSchema from "@theme/RequestSchema";
import StatusCodes from "@theme/StatusCodes";
import OperationTabs from "@theme/OperationTabs";
import TabItem from "@theme/TabItem";
import Heading from "@theme/Heading";

<Heading
  as={"h1"}
  className={"openapi__heading"}
  children={"Describe an agent by its ID."}
>
</Heading>

<MethodEndpoint
  method={"get"}
  path={"/v1alpha/agents/{agent_id}"}
  context={"endpoint"}
>

</MethodEndpoint>



Describe an agent by its ID.

<Heading
  id={"request"}
  as={"h2"}
  className={"openapi-tabs__heading"}
  children={"Request"}
>
</Heading>

<ParamsDetails
  parameters={[{"name":"agent_id","in":"path","description":"ID of the agent.","required":true,"schema":{"type":"string"}}]}
>

</ParamsDetails>

<RequestSchema
  title={"Body"}
  body={undefined}
>

</RequestSchema>

<StatusCodes
  id={undefined}
  label={undefined}
  responses={{"200":{"description":"An Agent of the agent.","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","description":"Unique identifier for the agent"},"agent_config":{"description":"Configuration settings for the agent","type":"object","properties":{"sampling_params":{"type":"object","properties":{"strategy":{"oneOf":[{"type":"object","properties":{"type":{"type":"string","const":"greedy","default":"greedy","description":"Must be \"greedy\" to identify this sampling strategy"}},"additionalProperties":false,"required":["type"],"title":"GreedySamplingStrategy","description":"Greedy sampling strategy that selects the highest probability token at each step."},{"type":"object","properties":{"type":{"type":"string","const":"top_p","default":"top_p","description":"Must be \"top_p\" to identify this sampling strategy"},"temperature":{"type":"number","description":"Controls randomness in sampling. Higher values increase randomness"},"top_p":{"type":"number","default":0.95,"description":"Cumulative probability threshold for nucleus sampling. Defaults to 0.95"}},"additionalProperties":false,"required":["type"],"title":"TopPSamplingStrategy","description":"Top-p (nucleus) sampling strategy that samples from the smallest set of tokens with cumulative probability >= p."},{"type":"object","properties":{"type":{"type":"string","const":"top_k","default":"top_k","description":"Must be \"top_k\" to identify this sampling strategy"},"top_k":{"type":"integer","description":"Number of top tokens to consider for sampling. Must be at least 1"}},"additionalProperties":false,"required":["type","top_k"],"title":"TopKSamplingStrategy","description":"Top-k sampling strategy that restricts sampling to the k most likely tokens."}],"discriminator":{"propertyName":"type","mapping":{"greedy":{"type":"object","properties":{"type":{"type":"string","const":"greedy","default":"greedy","description":"Must be \"greedy\" to identify this sampling strategy"}},"additionalProperties":false,"required":["type"],"title":"GreedySamplingStrategy","description":"Greedy sampling strategy that selects the highest probability token at each step."},"top_p":{"type":"object","properties":{"type":{"type":"string","const":"top_p","default":"top_p","description":"Must be \"top_p\" to identify this sampling strategy"},"temperature":{"type":"number","description":"Controls randomness in sampling. Higher values increase randomness"},"top_p":{"type":"number","default":0.95,"description":"Cumulative probability threshold for nucleus sampling. Defaults to 0.95"}},"additionalProperties":false,"required":["type"],"title":"TopPSamplingStrategy","description":"Top-p (nucleus) sampling strategy that samples from the smallest set of tokens with cumulative probability >= p."},"top_k":{"type":"object","properties":{"type":{"type":"string","const":"top_k","default":"top_k","description":"Must be \"top_k\" to identify this sampling strategy"},"top_k":{"type":"integer","description":"Number of top tokens to consider for sampling. Must be at least 1"}},"additionalProperties":false,"required":["type","top_k"],"title":"TopKSamplingStrategy","description":"Top-k sampling strategy that restricts sampling to the k most likely tokens."}}},"description":"The sampling strategy."},"max_tokens":{"type":"integer","default":0,"description":"The maximum number of tokens that can be generated in the completion. The token count of your prompt plus max_tokens cannot exceed the model's context length."},"repetition_penalty":{"type":"number","default":1,"description":"Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics."},"stop":{"type":"array","items":{"type":"string"},"description":"Up to 4 sequences where the API will stop generating further tokens. The returned text will not contain the stop sequence."}},"additionalProperties":false,"required":["strategy"],"title":"SamplingParams","description":"Sampling parameters."},"input_shields":{"type":"array","items":{"type":"string"}},"output_shields":{"type":"array","items":{"type":"string"}},"toolgroups":{"type":"array","items":{"oneOf":[{"type":"string"},{"type":"object","properties":{"name":{"type":"string"},"args":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]}}},"additionalProperties":false,"required":["name","args"],"title":"AgentToolGroupWithArgs"}],"title":"AgentTool"}},"client_tools":{"type":"array","items":{"type":"object","properties":{"toolgroup_id":{"type":"string","description":"(Optional) ID of the tool group this tool belongs to"},"name":{"type":"string","description":"Name of the tool"},"description":{"type":"string","description":"(Optional) Human-readable description of what the tool does"},"input_schema":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"(Optional) JSON Schema for tool inputs (MCP inputSchema)"},"output_schema":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"(Optional) JSON Schema for tool outputs (MCP outputSchema)"},"metadata":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"(Optional) Additional metadata about the tool"}},"additionalProperties":false,"required":["name"],"title":"ToolDef","description":"Tool definition used in runtime contexts."}},"tool_choice":{"type":"string","enum":["auto","required","none"],"title":"ToolChoice","description":"Whether tool use is required or automatic. This is a hint to the model which may not be followed. It depends on the Instruction Following capabilities of the model.","deprecated":true},"tool_prompt_format":{"type":"string","enum":["json","function_tag","python_list"],"title":"ToolPromptFormat","description":"Prompt format for calling custom / zero shot tools.","deprecated":true},"tool_config":{"type":"object","properties":{"tool_choice":{"oneOf":[{"type":"string","enum":["auto","required","none"],"title":"ToolChoice","description":"Whether tool use is required or automatic. This is a hint to the model which may not be followed. It depends on the Instruction Following capabilities of the model."},{"type":"string"}],"default":"auto","description":"(Optional) Whether tool use is automatic, required, or none. Can also specify a tool name to use a specific tool. Defaults to ToolChoice.auto."},"tool_prompt_format":{"type":"string","enum":["json","function_tag","python_list"],"description":"(Optional) Instructs the model how to format tool calls. By default, Llama Stack will attempt to use a format that is best adapted to the model. - `ToolPromptFormat.json`: The tool calls are formatted as a JSON object. - `ToolPromptFormat.function_tag`: The tool calls are enclosed in a <function=function_name> tag. - `ToolPromptFormat.python_list`: The tool calls are output as Python syntax -- a list of function calls."},"system_message_behavior":{"type":"string","enum":["append","replace"],"description":"(Optional) Config for how to override the default system prompt. - `SystemMessageBehavior.append`: Appends the provided system message to the default system prompt. - `SystemMessageBehavior.replace`: Replaces the default system prompt with the provided system message. The system message can include the string '{{function_definitions}}' to indicate where the function definitions should be inserted.","default":"append"}},"additionalProperties":false,"title":"ToolConfig","description":"Configuration for tool use."},"max_infer_iters":{"type":"integer","default":10},"model":{"type":"string","description":"The model identifier to use for the agent"},"instructions":{"type":"string","description":"The system instructions for the agent"},"name":{"type":"string","description":"Optional name for the agent, used in telemetry and identification"},"enable_session_persistence":{"type":"boolean","default":false,"description":"Optional flag indicating whether session data has to be persisted"},"response_format":{"description":"Optional response format configuration","oneOf":[{"type":"object","properties":{"type":{"type":"string","enum":["json_schema","grammar"],"description":"Must be \"json_schema\" to identify this format type","const":"json_schema","default":"json_schema"},"json_schema":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"The JSON schema the response should conform to. In a Python SDK, this is often a `pydantic` model."}},"additionalProperties":false,"required":["type","json_schema"],"title":"JsonSchemaResponseFormat","description":"Configuration for JSON schema-guided response generation."},{"type":"object","properties":{"type":{"type":"string","enum":["json_schema","grammar"],"description":"Must be \"grammar\" to identify this format type","const":"grammar","default":"grammar"},"bnf":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"The BNF grammar specification the response should conform to"}},"additionalProperties":false,"required":["type","bnf"],"title":"GrammarResponseFormat","description":"Configuration for grammar-guided response generation."}],"discriminator":{"propertyName":"type","mapping":{"json_schema":{"type":"object","properties":{"type":{"type":"string","enum":["json_schema","grammar"],"description":"Must be \"json_schema\" to identify this format type","const":"json_schema","default":"json_schema"},"json_schema":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"The JSON schema the response should conform to. In a Python SDK, this is often a `pydantic` model."}},"additionalProperties":false,"required":["type","json_schema"],"title":"JsonSchemaResponseFormat","description":"Configuration for JSON schema-guided response generation."},"grammar":{"type":"object","properties":{"type":{"type":"string","enum":["json_schema","grammar"],"description":"Must be \"grammar\" to identify this format type","const":"grammar","default":"grammar"},"bnf":{"type":"object","additionalProperties":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}]},"description":"The BNF grammar specification the response should conform to"}},"additionalProperties":false,"required":["type","bnf"],"title":"GrammarResponseFormat","description":"Configuration for grammar-guided response generation."}}},"title":"ResponseFormat"}},"additionalProperties":false,"required":["model","instructions"],"title":"AgentConfig"},"created_at":{"type":"string","format":"date-time","description":"Timestamp when the agent was created"}},"additionalProperties":false,"required":["agent_id","agent_config","created_at"],"title":"Agent","description":"An agent instance with configuration and metadata."}}}},"400":{"description":"The request was invalid or malformed","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"title":{"type":"string","description":"Error title, a short summary of the error which is invariant for an error type"},"detail":{"type":"string","description":"Error detail, a longer human-readable description of the error"},"instance":{"type":"string","description":"(Optional) A URL which can be used to retrieve more information about the specific occurrence of the error"}},"additionalProperties":false,"required":["status","title","detail"],"title":"Error","description":"Error response from the API. Roughly follows RFC 7807."},"example":{"status":400,"title":"Bad Request","detail":"The request was invalid or malformed"}}}},"429":{"description":"The client has sent too many requests in a given amount of time","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"title":{"type":"string","description":"Error title, a short summary of the error which is invariant for an error type"},"detail":{"type":"string","description":"Error detail, a longer human-readable description of the error"},"instance":{"type":"string","description":"(Optional) A URL which can be used to retrieve more information about the specific occurrence of the error"}},"additionalProperties":false,"required":["status","title","detail"],"title":"Error","description":"Error response from the API. Roughly follows RFC 7807."},"example":{"status":429,"title":"Too Many Requests","detail":"You have exceeded the rate limit. Please try again later."}}}},"500":{"description":"The server encountered an unexpected error","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"title":{"type":"string","description":"Error title, a short summary of the error which is invariant for an error type"},"detail":{"type":"string","description":"Error detail, a longer human-readable description of the error"},"instance":{"type":"string","description":"(Optional) A URL which can be used to retrieve more information about the specific occurrence of the error"}},"additionalProperties":false,"required":["status","title","detail"],"title":"Error","description":"Error response from the API. Roughly follows RFC 7807."},"example":{"status":500,"title":"Internal Server Error","detail":"An unexpected error occurred. Our team has been notified."}}}},"default":{"description":"An unexpected error occurred","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"integer","description":"HTTP status code"},"title":{"type":"string","description":"Error title, a short summary of the error which is invariant for an error type"},"detail":{"type":"string","description":"Error detail, a longer human-readable description of the error"},"instance":{"type":"string","description":"(Optional) A URL which can be used to retrieve more information about the specific occurrence of the error"}},"additionalProperties":false,"required":["status","title","detail"],"title":"Error","description":"Error response from the API. Roughly follows RFC 7807."},"example":{"status":0,"title":"Error","detail":"An unexpected error occurred"}}}}}}
>

</StatusCodes>