llama-stack-mirror/docs/docs/api/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/llama-stack-specification
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={"/v1/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":{"description":"The sampling 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."}}},"title":"SamplingStrategy"},"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":{"name":{"type":"string","description":"Name of the tool"},"description":{"type":"string","description":"(Optional) Human-readable description of what the tool does"},"parameters":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Name of the parameter"},"parameter_type":{"type":"string","description":"Type of the parameter (e.g., string, integer)"},"description":{"type":"string","description":"Human-readable description of what the parameter does"},"required":{"type":"boolean","default":true,"description":"Whether this parameter is required for tool invocation"},"default":{"oneOf":[{"type":"null"},{"type":"boolean"},{"type":"number"},{"type":"string"},{"type":"array"},{"type":"object"}],"description":"(Optional) Default value for the parameter if not provided"}},"additionalProperties":false,"required":["name","parameter_type","description","required"],"title":"ToolParameter","description":"Parameter definition for a tool."},"description":"(Optional) List of parameters this tool accepts"},"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>