> This page is for version v5.0 (default). > For other versions, use one of these documentation indexes: > - v5.0 (default): https://humanloop.com/docs/v5/llms.txt > - v4.0: https://humanloop.com/docs/v4/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://humanloop.com/docs/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://humanloop.com/docs/_mcp/server. > Humanloop Agents enable you to build and monitor complex AI workflows, from simple tool calling to sophisticated multi-step processes. Create, test, and deploy Agents through our UI or API. ![](/docs/_fern-img/112487b0225538e4fd70eef3fb80c524fbea9c10e39c7f505a979858c0537a14.webp) > **Warning** > > Agents are currently in beta and subject to change. ## Overview A Humanloop Agent is a multi-step AI system that leverages an LLM, external information sources and tool calling to accomplish complex tasks automatically. It comprises a main orchestrator LLM that utilizes tools to accomplish its task. An Agent is composed primarily of: * A **template** that instructs the Agent model how to process tasks * Model **parameters** such as `temperature`, `max_tokens`, and `reasoning_effort` * The **workflow configuration** that defines how the Agent processes tasks, such as `max_iterations` and `stopping_tools` * The available **tools** the Agent can use, including [Tools](/docs/v5/explanation/tools) and [Prompts](/docs/v5/explanation/prompts) An Agent executes on the Humanloop platform: for a given Agent version, if you supply the necessary inputs, it will execute until it reaches a stopping condition. Humanloop will return a [Log](/docs/v5/explanation/logs) with an `output` or `output_message`, along with the full trace of the Agent's execution. Inputs are defined through **variables** in the Agent template. The values of these variables will need to be supplied when you call the Agent to create a generation. The Agent configuration and runtime data will be stored in Logs, which can then be used to create Datasets for evaluation purposes. ## Basics You can create and configure Agents through the Humanloop UI or programmatically via our SDK. ### Agents in the UI To create an Agent, create a new file and select the **Agent** option. ![](/docs/_fern-img/cb68d518a2c22dec1a7f9e637c152d1e0f8d95070776ade8c70c15f9d8a51ed2.webp) Then, use the Agent Editor to configure and test the Agent. You can link existing Tools and Prompts from your workspace for the Agent to use. You can also define a tool inline by providing its JSON schema. You can also configure the `max_iterations` and `stopping_tools` for the Agent in the "Parameters" section. ![](/docs/_fern-img/9a4bf2808ac5b0cc3089d2b9f61a8a64380e10bae11e25ccaee151ef313fcaae.webp) ### Agents via the SDK To create an Agent programmatically, use our SDK. ```curl curl -X POST https://api.humanloop.com/v5/agents \ -H "X-API-Key: $YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "Banking/Teller Agent", "provider": "anthropic", "endpoint": "chat", "model": "claude-3-7-sonnet-latest", "reasoning_effort": 1024, "template": [ { "role": "system", "content": "You are a helpful a digital bank teller, you help users navigate our digital banking platform." }, ], "max_iterations": 3, "tools": [ { "type": "file", "link": { "file_id": "pr_1234567890", "version_id": "prv_1234567890" }, "on_agent_call": "continue" }, { "type": "json_schema", "json_schema": { "name": "stop", "description": "Call this tool when you have finished your task.", "parameters": { "type": "object", "properties": { "output": { "type": "string", } } } } }, ] }' ``` Agents can be called through our UI for testing and development, or via API for production deployments. ```curl curl -X POST https://api.humanloop.com/v5/agents/call \ -H "X-API-Key: $YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "Banking/Teller Agent", "messages": [ { "role": "user", "content": "I need to withdraw $1000" } ] }' ``` If your Agent calls a tool that Humanloop cannot run, the system will pause and wait until you provide the response required by the tool. You can then continue the Agent's execution using the `/continue` endpoint. ```curl curl -X POST https://api.humanloop.com/v5/agents/continue \ -H "X-API-Key: $YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "log_id": "log_1234567890", "messages": [ { "role": "tool", "tool_call_id": "tool_call_1234567890", "content": "Not enough funds. Politely decline user request." } ] "stream": false }' ``` You can also log Agent executions explicitly when running the Agent logic yourself: ```curl curl -X POST https://api.humanloop.com/v5/agents/log \ -H "X-API-Key: $YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "path": "Banking/Teller Agent", "messages": [ { "role": "user", "content": "I need to withdraw $1000" }, ] }' ``` ## Versioning Versioning your Agents enables you to track how adjustments to template, tools, or model parameters influence the Agent's behavior. This is crucial for iterative development, as you can pinpoint which configuration produces the most effective results for your use cases. You can use the Editor or SDK to create and update Agent Versions and iterate on improving its performance. The following components of an Agent contribute to its version: * The Agent's **template** -- the system prompt and any other instructions * The model call **parameters** -- such as `temperature`, `max_tokens`, and `reasoning_effort` * The Agent's **workflow** configuration -- such as `max_iterations` and `stopping_tools` * The Agent's **tools** -- including both inline JSON Schema tools and linked Tool or Prompt Versions ## Stopping Conditions An Agent will stop executing in three circumstances: 1. The maximum number of iterations is reached 2. The Agent executes a tool that is configured to stop the Agent 3. The Agent has generated a response with no further tool calls ### Max Iterations You can cap the maximum number of iterations an Agent can execute--the Agent will generate up to `max_iterations` times, and then stop. This results in an Agent Log with a `finish_reason` of `"max_iterations_reached"`. ### Stopping Tools You can designate that a tool should stop the Agent after it is called. If it can be run on Humanloop, it will be run and the result logged before the Agent stops. This results in an Agent Log with a `finish_reason` of `"stopping_tool_called"` and `stopping_tool_names` populated. ### Agent Finished Lastly, the Agent will stop if it has generated a response with no further tool calls. This represents a natural end to the Agent's execution, and results in an Agent Log with a `finish_reason` of `"agent_generation_finished"`. ## Evaluation Agents can be evaluated both through the Humanloop UI and programmatically. After each Agent execution, configured evaluators will run automatically on Humanloop. Get started with [evaluating your Agents in the UI](/docs/tutorials/evaluate-agent-in-ui) or [programmatically](/docs/tutorials/agent-evaluation-code). ## Tracing A trace is the collection of Logs associated with an Agent execution, showing the complete path from input to output, including all intermediate steps. Every Agent trace includes: * The initial input and messages, and final output * All intermediate LLM calls and their responses as nested Logs * Tools called by the Agent and their inputs and outputs as nested Logs * Any errors or unexpected behaviors * Timing and performance metrics ![](/docs/_fern-img/6fb0d8bd019efbc9cb8f1e6c23342aac254d709c88b6d56d7fded616bb207e35.webp) ### Metrics and Timing Cost, latency, execution time, and token usage metrics are captured for each trace. They span from the earliest interaction to the final response. ## Serialization The .agent file format is a serialized representation of an Agent Version, designed to be human-readable and suitable for integration into version control systems alongside code. The format is heavily inspired by MDX, with model and parameters specified in a YAML header alongside JSX-style syntax for chat templates. **`.agent`** ```jsx title=".agent" maxLines=75 --- model: claude-3-7-sonnet-latest max_tokens: -1 provider: anthropic endpoint: chat reasoning_effort: 1024 tools: [ { "type": "file", "link": { "file_id": "pr_1234567890", "version_id": "prv_1234567890" }, "on_agent_call": "continue" }, { "type": "file", "link": { "file_id": "tl_1234567890", "version_id": "tlv_1234567890" }, "on_agent_call": "stop" }, { "type": "inline", "json_schema": { "name": "stop", "description": "Call this tool when you have finished your task.", "parameters": { "type": "object", "properties": { "output": { "type": "string", "description": "The final output to return to the user." } }, "additionalProperties": false, "required": [ "output" ] }, "strict": true }, "on_agent_call": "stop" }, { "type": "file", "link": { "file_id": "tl_cBfvZ3Xre8PAfVAa5r9P6", "version_id": "tlv_gzr3bxaVGu889O4lsOgtG" }, "on_agent_call": "continue" }, ] --- You are a helpful a digital bank teller, you help users navigate our digital banking platform. In your interactions, follow these guidelines: {{personality}}. Notify them about the following policies: {{policies}}. ``` ## Next steps You now understand the role of Agents in the Humanloop ecosystem. Explore the following resources to apply Agents to your AI project: * See our tutorials to learn how to evaluate your Agent [via UI](/docs/guides/evals/run-evaluation-ui) or [via code](/docs/guides/evals/run-evaluation-api). * Explore our [Tools documentation](/docs/v5/explanation/tools) to understand what capabilities you can give your Agents.