Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.mka1.com/llms.txt

Use this file to discover all available pages before exploring further.

Use the Agents API when you want first-class, reusable agent objects instead of building a Responses request from scratch every time. An agent stores model choice, instructions, and tool configuration. Each run persists the input plus the upstream Responses API result. API Reference:

​
Create an agent

Create an agent once, then reuse its saved behavior across multiple runs. The example below stores instructions and a web_search tool so later runs can call external tools when needed. 
mka1 agents create --body '{
  "name": "release-research-agent",
  "description": "Looks up current release information before answering.",
  "model": "auto",
  "instructions": "Use web search when the question depends on current external information.",
  "tools": [
    {
      "type": "web_search",
      "search_context_size": "medium"
    }
  ],
  "tool_choice": "auto",
  "parallel_tool_calls": true,
  "metadata": {
    "team": "docs"
  }
}' \
  -H 'X-On-Behalf-Of: <end-user-id>'
The response is an agent object with a stable id such as agt_.... See the Create an agent API reference for the full schema.

​
List and retrieve agents

Use the collection endpoint to list saved agents for the current caller. Use the item endpoint when you already know the agent ID. 
# List agents
mka1 agents list --order desc

# Retrieve a single agent by id
mka1 agents get --agent-id agt_123
See the List agents API reference and Retrieve an agent API reference for the complete response shapes.

​
Execute a saved agent

Run the agent by sending only the per-run input and optional metadata. The service combines this with the saved agent configuration and forwards the request into the Responses API through mkllm-gateway. 
mka1 agent-runs create --agent-id agt_123 --body '{
  "input": [
    {
      "type": "text",
      "text": "What is Bun'"'"'s current stable version? Use web search before answering."
    }
  ],
  "metadata": {
    "request_source": "docs"
  }
}'
The run response includes:
  • the persisted run ID
  • the run status
  • gateway_response_id from the upstream Responses call
  • gateway_response, which contains the stored assistant output and any tool activity
If the run used web_search, the persisted gateway_response will include the corresponding tool call entries. See the Execute a saved agent API reference for the full run request and response schema.

​
Inspect run history

Use the runs collection to list prior executions for one agent. Use the run detail endpoint to retrieve one stored result again later. 
# List runs for an agent
mka1 agent-runs list --agent-id agt_123

# Retrieve a single run
mka1 agent-runs get --agent-id agt_123 --run-id run_123
To retrieve one run directly: 
curl https://apigw.mka1.com/api/v1/agents/agt_123/runs/run_123 \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'
See the List runs for an agent API reference and Retrieve an agent run API reference for the complete run-history schema.

​
Update or delete an agent

Use POST /api/v1/agents/{agent_id} to update stored configuration. Use DELETE /api/v1/agents/{agent_id} to soft-delete the agent when it should no longer accept new runs. 
curl https://apigw.mka1.com/api/v1/agents/agt_123 \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>' \
  --data '{
    "instructions": "Use web search for current information. Reply in 3 bullets max."
  }'

curl https://apigw.mka1.com/api/v1/agents/agt_123 \
  --request DELETE \
  --header 'Authorization: Bearer <mka1-api-key>' \
  --header 'X-On-Behalf-Of: <end-user-id>'
See the Update an agent API reference and Delete an agent API reference for the endpoint details. Review the Responses API guide if you want to compare saved-agent execution with one-off response requests.