curl --request POST \
--url https://api.example.com/api/conversations \
--header 'Content-Type: application/json' \
--data '
{
"agent": {
"llm": {
"model": "your-model-provider/your-model-name",
"api_key": "**********",
"temperature": 0,
"usage_id": "your-llm-service"
},
"tools": [
{
"name": "terminal"
},
{
"name": "file_editor"
},
{
"name": "task_tracker"
},
{
"name": "browser_tool_set"
}
],
"system_prompt_kwargs": {
"llm_security_analyzer": true
},
"kind": "Agent"
},
"workspace": {
"working_dir": "workspace/project",
"kind": "LocalWorkspace"
},
"initial_message": {
"content": [
{
"text": "Flip a coin!"
}
]
}
}
'import requests
url = "https://api.example.com/api/conversations"
payload = {
"agent": {
"llm": {
"model": "your-model-provider/your-model-name",
"api_key": "**********",
"temperature": 0,
"usage_id": "your-llm-service"
},
"tools": [{ "name": "terminal" }, { "name": "file_editor" }, { "name": "task_tracker" }, { "name": "browser_tool_set" }],
"system_prompt_kwargs": { "llm_security_analyzer": True },
"kind": "Agent"
},
"workspace": {
"working_dir": "workspace/project",
"kind": "LocalWorkspace"
},
"initial_message": { "content": [{ "text": "Flip a coin!" }] }
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
agent: {
llm: {
model: 'your-model-provider/your-model-name',
api_key: '**********',
temperature: 0,
usage_id: 'your-llm-service'
},
tools: [
{name: 'terminal'},
{name: 'file_editor'},
{name: 'task_tracker'},
{name: 'browser_tool_set'}
],
system_prompt_kwargs: {llm_security_analyzer: true},
kind: 'Agent'
},
workspace: {working_dir: 'workspace/project', kind: 'LocalWorkspace'},
initial_message: {content: [{text: 'Flip a coin!'}]}
})
};
fetch('https://api.example.com/api/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent' => [
'llm' => [
'model' => 'your-model-provider/your-model-name',
'api_key' => '**********',
'temperature' => 0,
'usage_id' => 'your-llm-service'
],
'tools' => [
[
'name' => 'terminal'
],
[
'name' => 'file_editor'
],
[
'name' => 'task_tracker'
],
[
'name' => 'browser_tool_set'
]
],
'system_prompt_kwargs' => [
'llm_security_analyzer' => true
],
'kind' => 'Agent'
],
'workspace' => [
'working_dir' => 'workspace/project',
'kind' => 'LocalWorkspace'
],
'initial_message' => [
'content' => [
[
'text' => 'Flip a coin!'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/conversations"
payload := strings.NewReader("{\n \"agent\": {\n \"llm\": {\n \"model\": \"your-model-provider/your-model-name\",\n \"api_key\": \"**********\",\n \"temperature\": 0,\n \"usage_id\": \"your-llm-service\"\n },\n \"tools\": [\n {\n \"name\": \"terminal\"\n },\n {\n \"name\": \"file_editor\"\n },\n {\n \"name\": \"task_tracker\"\n },\n {\n \"name\": \"browser_tool_set\"\n }\n ],\n \"system_prompt_kwargs\": {\n \"llm_security_analyzer\": true\n },\n \"kind\": \"Agent\"\n },\n \"workspace\": {\n \"working_dir\": \"workspace/project\",\n \"kind\": \"LocalWorkspace\"\n },\n \"initial_message\": {\n \"content\": [\n {\n \"text\": \"Flip a coin!\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/conversations")
.header("Content-Type", "application/json")
.body("{\n \"agent\": {\n \"llm\": {\n \"model\": \"your-model-provider/your-model-name\",\n \"api_key\": \"**********\",\n \"temperature\": 0,\n \"usage_id\": \"your-llm-service\"\n },\n \"tools\": [\n {\n \"name\": \"terminal\"\n },\n {\n \"name\": \"file_editor\"\n },\n {\n \"name\": \"task_tracker\"\n },\n {\n \"name\": \"browser_tool_set\"\n }\n ],\n \"system_prompt_kwargs\": {\n \"llm_security_analyzer\": true\n },\n \"kind\": \"Agent\"\n },\n \"workspace\": {\n \"working_dir\": \"workspace/project\",\n \"kind\": \"LocalWorkspace\"\n },\n \"initial_message\": {\n \"content\": [\n {\n \"text\": \"Flip a coin!\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent\": {\n \"llm\": {\n \"model\": \"your-model-provider/your-model-name\",\n \"api_key\": \"**********\",\n \"temperature\": 0,\n \"usage_id\": \"your-llm-service\"\n },\n \"tools\": [\n {\n \"name\": \"terminal\"\n },\n {\n \"name\": \"file_editor\"\n },\n {\n \"name\": \"task_tracker\"\n },\n {\n \"name\": \"browser_tool_set\"\n }\n ],\n \"system_prompt_kwargs\": {\n \"llm_security_analyzer\": true\n },\n \"kind\": \"Agent\"\n },\n \"workspace\": {\n \"working_dir\": \"workspace/project\",\n \"kind\": \"LocalWorkspace\"\n },\n \"initial_message\": {\n \"content\": [\n {\n \"text\": \"Flip a coin!\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent": {
"llm": {
"api_key": "your_api_key_here",
"base_url": "https://llm-proxy.eval.all-hands.dev",
"model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929"
},
"kind": "Agent",
"tools": {
"name": "TerminalTool",
"params": {}
},
"mcp_config": {
"mcpServers": {
"fetch": {
"args": [
"mcp-server-fetch"
],
"command": "uvx"
}
}
},
"filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
"include_default_tools": [
"FinishTool",
"ThinkTool"
],
"agent_context": {
"skills": [
{
"content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.",
"name": "AGENTS.md",
"type": "repo"
},
{
"content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are",
"name": "flarglebargle",
"trigger": [
"flarglebargle"
],
"type": "knowledge"
}
],
"system_message_suffix": "Always finish your response with the word 'yay!'"
},
"system_prompt_filename": "system_prompt.j2",
"security_policy_filename": "security_policy.j2",
"system_prompt_kwargs": {
"cli_mode": true
},
"condenser": {
"keep_first": 10,
"kind": "LLMSummarizingCondenser",
"llm": {
"api_key": "your_api_key_here",
"base_url": "https://llm-proxy.eval.all-hands.dev",
"model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929"
},
"max_size": 80
},
"critic": {
"kind": "AgentFinishedCritic"
}
},
"workspace": {
"working_dir": "<string>",
"kind": "LocalWorkspace"
},
"persistence_dir": "workspace/conversations",
"max_iterations": 500,
"stuck_detection": true,
"execution_status": "idle",
"confirmation_policy": {
"kind": "NeverConfirm"
},
"security_analyzer": {
"kind": "GraySwanAnalyzer",
"history_limit": 20,
"max_message_chars": 30000,
"timeout": 30,
"low_threshold": 0.3,
"medium_threshold": 0.7,
"api_url": "https://api.grayswan.ai/cygnal/monitor",
"api_key": "<string>",
"policy_id": "<string>"
},
"activated_knowledge_skills": [
"<string>"
],
"blocked_actions": {},
"blocked_messages": {},
"stats": {},
"secret_registry": {
"secret_sources": {}
},
"agent_state": {},
"title": "<string>",
"metrics": {
"model_name": "default",
"accumulated_cost": 0,
"max_budget_per_task": 123,
"accumulated_token_usage": {
"model": "",
"prompt_tokens": 0,
"completion_tokens": 0,
"cache_read_tokens": 0,
"cache_write_tokens": 0,
"reasoning_tokens": 0,
"context_window": 0,
"per_turn_token": 0,
"response_id": ""
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Start Conversation
Start a conversation in the local environment.
curl --request POST \
--url https://api.example.com/api/conversations \
--header 'Content-Type: application/json' \
--data '
{
"agent": {
"llm": {
"model": "your-model-provider/your-model-name",
"api_key": "**********",
"temperature": 0,
"usage_id": "your-llm-service"
},
"tools": [
{
"name": "terminal"
},
{
"name": "file_editor"
},
{
"name": "task_tracker"
},
{
"name": "browser_tool_set"
}
],
"system_prompt_kwargs": {
"llm_security_analyzer": true
},
"kind": "Agent"
},
"workspace": {
"working_dir": "workspace/project",
"kind": "LocalWorkspace"
},
"initial_message": {
"content": [
{
"text": "Flip a coin!"
}
]
}
}
'import requests
url = "https://api.example.com/api/conversations"
payload = {
"agent": {
"llm": {
"model": "your-model-provider/your-model-name",
"api_key": "**********",
"temperature": 0,
"usage_id": "your-llm-service"
},
"tools": [{ "name": "terminal" }, { "name": "file_editor" }, { "name": "task_tracker" }, { "name": "browser_tool_set" }],
"system_prompt_kwargs": { "llm_security_analyzer": True },
"kind": "Agent"
},
"workspace": {
"working_dir": "workspace/project",
"kind": "LocalWorkspace"
},
"initial_message": { "content": [{ "text": "Flip a coin!" }] }
}
headers = {"Content-Type": "application/json"}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'Content-Type': 'application/json'},
body: JSON.stringify({
agent: {
llm: {
model: 'your-model-provider/your-model-name',
api_key: '**********',
temperature: 0,
usage_id: 'your-llm-service'
},
tools: [
{name: 'terminal'},
{name: 'file_editor'},
{name: 'task_tracker'},
{name: 'browser_tool_set'}
],
system_prompt_kwargs: {llm_security_analyzer: true},
kind: 'Agent'
},
workspace: {working_dir: 'workspace/project', kind: 'LocalWorkspace'},
initial_message: {content: [{text: 'Flip a coin!'}]}
})
};
fetch('https://api.example.com/api/conversations', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.example.com/api/conversations",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent' => [
'llm' => [
'model' => 'your-model-provider/your-model-name',
'api_key' => '**********',
'temperature' => 0,
'usage_id' => 'your-llm-service'
],
'tools' => [
[
'name' => 'terminal'
],
[
'name' => 'file_editor'
],
[
'name' => 'task_tracker'
],
[
'name' => 'browser_tool_set'
]
],
'system_prompt_kwargs' => [
'llm_security_analyzer' => true
],
'kind' => 'Agent'
],
'workspace' => [
'working_dir' => 'workspace/project',
'kind' => 'LocalWorkspace'
],
'initial_message' => [
'content' => [
[
'text' => 'Flip a coin!'
]
]
]
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.example.com/api/conversations"
payload := strings.NewReader("{\n \"agent\": {\n \"llm\": {\n \"model\": \"your-model-provider/your-model-name\",\n \"api_key\": \"**********\",\n \"temperature\": 0,\n \"usage_id\": \"your-llm-service\"\n },\n \"tools\": [\n {\n \"name\": \"terminal\"\n },\n {\n \"name\": \"file_editor\"\n },\n {\n \"name\": \"task_tracker\"\n },\n {\n \"name\": \"browser_tool_set\"\n }\n ],\n \"system_prompt_kwargs\": {\n \"llm_security_analyzer\": true\n },\n \"kind\": \"Agent\"\n },\n \"workspace\": {\n \"working_dir\": \"workspace/project\",\n \"kind\": \"LocalWorkspace\"\n },\n \"initial_message\": {\n \"content\": [\n {\n \"text\": \"Flip a coin!\"\n }\n ]\n }\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.example.com/api/conversations")
.header("Content-Type", "application/json")
.body("{\n \"agent\": {\n \"llm\": {\n \"model\": \"your-model-provider/your-model-name\",\n \"api_key\": \"**********\",\n \"temperature\": 0,\n \"usage_id\": \"your-llm-service\"\n },\n \"tools\": [\n {\n \"name\": \"terminal\"\n },\n {\n \"name\": \"file_editor\"\n },\n {\n \"name\": \"task_tracker\"\n },\n {\n \"name\": \"browser_tool_set\"\n }\n ],\n \"system_prompt_kwargs\": {\n \"llm_security_analyzer\": true\n },\n \"kind\": \"Agent\"\n },\n \"workspace\": {\n \"working_dir\": \"workspace/project\",\n \"kind\": \"LocalWorkspace\"\n },\n \"initial_message\": {\n \"content\": [\n {\n \"text\": \"Flip a coin!\"\n }\n ]\n }\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.example.com/api/conversations")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent\": {\n \"llm\": {\n \"model\": \"your-model-provider/your-model-name\",\n \"api_key\": \"**********\",\n \"temperature\": 0,\n \"usage_id\": \"your-llm-service\"\n },\n \"tools\": [\n {\n \"name\": \"terminal\"\n },\n {\n \"name\": \"file_editor\"\n },\n {\n \"name\": \"task_tracker\"\n },\n {\n \"name\": \"browser_tool_set\"\n }\n ],\n \"system_prompt_kwargs\": {\n \"llm_security_analyzer\": true\n },\n \"kind\": \"Agent\"\n },\n \"workspace\": {\n \"working_dir\": \"workspace/project\",\n \"kind\": \"LocalWorkspace\"\n },\n \"initial_message\": {\n \"content\": [\n {\n \"text\": \"Flip a coin!\"\n }\n ]\n }\n}"
response = http.request(request)
puts response.read_body{
"id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"agent": {
"llm": {
"api_key": "your_api_key_here",
"base_url": "https://llm-proxy.eval.all-hands.dev",
"model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929"
},
"kind": "Agent",
"tools": {
"name": "TerminalTool",
"params": {}
},
"mcp_config": {
"mcpServers": {
"fetch": {
"args": [
"mcp-server-fetch"
],
"command": "uvx"
}
}
},
"filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
"include_default_tools": [
"FinishTool",
"ThinkTool"
],
"agent_context": {
"skills": [
{
"content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.",
"name": "AGENTS.md",
"type": "repo"
},
{
"content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are",
"name": "flarglebargle",
"trigger": [
"flarglebargle"
],
"type": "knowledge"
}
],
"system_message_suffix": "Always finish your response with the word 'yay!'"
},
"system_prompt_filename": "system_prompt.j2",
"security_policy_filename": "security_policy.j2",
"system_prompt_kwargs": {
"cli_mode": true
},
"condenser": {
"keep_first": 10,
"kind": "LLMSummarizingCondenser",
"llm": {
"api_key": "your_api_key_here",
"base_url": "https://llm-proxy.eval.all-hands.dev",
"model": "litellm_proxy/anthropic/claude-sonnet-4-5-20250929"
},
"max_size": 80
},
"critic": {
"kind": "AgentFinishedCritic"
}
},
"workspace": {
"working_dir": "<string>",
"kind": "LocalWorkspace"
},
"persistence_dir": "workspace/conversations",
"max_iterations": 500,
"stuck_detection": true,
"execution_status": "idle",
"confirmation_policy": {
"kind": "NeverConfirm"
},
"security_analyzer": {
"kind": "GraySwanAnalyzer",
"history_limit": 20,
"max_message_chars": 30000,
"timeout": 30,
"low_threshold": 0.3,
"medium_threshold": 0.7,
"api_url": "https://api.grayswan.ai/cygnal/monitor",
"api_key": "<string>",
"policy_id": "<string>"
},
"activated_knowledge_skills": [
"<string>"
],
"blocked_actions": {},
"blocked_messages": {},
"stats": {},
"secret_registry": {
"secret_sources": {}
},
"agent_state": {},
"title": "<string>",
"metrics": {
"model_name": "default",
"accumulated_cost": 0,
"max_budget_per_task": 123,
"accumulated_token_usage": {
"model": "",
"prompt_tokens": 0,
"completion_tokens": 0,
"cache_read_tokens": 0,
"cache_write_tokens": 0,
"reasoning_tokens": 0,
"context_window": 0,
"per_turn_token": 0,
"response_id": ""
}
},
"created_at": "2023-11-07T05:31:56Z",
"updated_at": "2023-11-07T05:31:56Z"
}{
"detail": [
{
"loc": [
"<string>"
],
"msg": "<string>",
"type": "<string>"
}
]
}Body
Payload to create a new conversation.
Contains an Agent configuration along with conversation-specific options.
Main agent implementation for OpenHands.
The Agent class provides the core functionality for running AI agents that can interact with tools, process messages, and execute actions. It inherits from AgentBase and implements the agent execution logic. Critic-related functionality is provided by CriticMixin.
Example: >>> from openhands.sdk import LLM, Agent, Tool >>> llm = LLM(model="claude-sonnet-4-20250514", api_key=SecretStr("key")) >>> tools = [Tool(name="TerminalTool"), Tool(name="FileEditorTool")] >>> agent = Agent(llm=llm, tools=tools)
Show child attributes
Show child attributes
Optional hook configuration for this conversation. Hooks are shell scripts that run at key lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, etc.). If both hook_config and plugins are provided, they are merged with explicit hooks running before plugin hooks.
Show child attributes
Show child attributes
Response
Successful Response
Information about a conversation running locally without a Runtime sandbox.
Dictionary for agent-specific runtime state that persists across iterations. Agents can store feature-specific state using string keys. To trigger autosave, always reassign: state.agent_state = {**state.agent_state, key: value}. See https://docs.openhands.dev/sdk/guides/convo-persistence#how-state-persistence-works
Was this page helpful?

