Skip to main content
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. 
const response = await fetch("https://apigw.mka1.com/api/v1/agents", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    name: "release-research-agent",
    description: "Looks up current release information before answering.",
    model: "meetkai:functionary-urdu-mini-pak",
    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"
    }
  }),
});

const agent = await response.json();
console.log(agent.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. 
const listResponse = await fetch("https://apigw.mka1.com/api/v1/agents?limit=20&order=desc", {
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const agents = await listResponse.json();
console.log(agents.data.map((agent) => agent.id));
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. 
const runResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
  body: JSON.stringify({
    input: [
      {
        type: "text",
        text: "What is Bun's current stable version? Use web search before answering.",
      },
    ],
    metadata: {
      request_source: "docs"
    }
  }),
});

const run = await runResponse.json();
console.log(run.gateway_response_id);
console.log(run.status);
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. 
const runsResponse = await fetch("https://apigw.mka1.com/api/v1/agents/agt_123/runs", {
  headers: {
    Authorization: "Bearer <mka1-api-key>",
    "X-On-Behalf-Of": "<end-user-id>",
  },
});

const runs = await runsResponse.json();
console.log(runs.data[0]?.id);
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.