Create an AI Agent

In this tutorial you will create an AI agent inside a workspace, execute a run, and inspect the results. By the end you will have a working agent that can process tasks autonomously.

Prerequisites

• A Chainabit account with a valid access token
• curl available in your terminal
• An existing workspace (see Workspaces API)

Set your environment variables:

export TOKEN="your-access-token"
export WORKSPACE_ID="ws_01HQ..."

---

Step 1: Create an Agent Definition

Define a new AI agent in your workspace. An agent definition describes what the agent does and how it behaves:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/ai/agents" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Summary Agent",
    "description": "Generates a daily summary of completed activities",
    "instructions": "Analyze the user'\''s completed bits for today and produce a concise summary with highlights and suggestions.",
    "modelId": "model_01HQ..."
  }'

JavaScript

const res = await fetch(`https://api.chainabit.com/api/v1/workspaces/${WORKSPACE_ID}/ai/agents`, {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${TOKEN}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Daily Summary Agent',
    description: 'Generates a daily summary of completed activities',
    instructions:
      "Analyze the user's completed bits for today and produce a concise summary with highlights and suggestions.",
    modelId: 'model_01HQ...',
  }),
});
const data = await res.json();
console.log(data);

Python

import requests

res = requests.post(
    f"{BASE}/workspaces/{WORKSPACE_ID}/ai/agents",
    headers={
        "Authorization": f"Bearer {TOKEN}",
        "Content-Type": "application/json",
    },
    json={
        "name": "Daily Summary Agent",
        "description": "Generates a daily summary of completed activities",
        "instructions": "Analyze the user's completed bits for today and produce a concise summary with highlights and suggestions.",
        "modelId": "model_01HQ...",
    },
)
print(res.json())

Response:

{
  "data": {
    "id": "agent_01HQA...",
    "workspaceId": "ws_01HQ...",
    "name": "Daily Summary Agent",
    "description": "Generates a daily summary of completed activities",
    "status": "active",
    "createdAt": "2026-03-17T10:00:00.000Z"
  }
}

Save the agent ID:

export AGENT_ID="agent_01HQA..."

---

Step 2: Run the Agent

Trigger an execution run for the agent. You can pass input parameters that the agent uses during processing:

cURL

curl -s -X POST "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/ai/agents/$AGENT_ID/runs" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "date": "2026-03-17"
    }
  }'

JavaScript

const res = await fetch(
  `https://api.chainabit.com/api/v1/workspaces/${WORKSPACE_ID}/ai/agents/${AGENT_ID}/runs`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      input: { date: '2026-03-17' },
    }),
  },
);
const data = await res.json();
console.log(data);

Python

res = requests.post(
    f"{BASE}/workspaces/{WORKSPACE_ID}/ai/agents/{AGENT_ID}/runs",
    headers={"Authorization": f"Bearer {TOKEN}"},
    json={"input": {"date": "2026-03-17"}},
)
print(res.json())

Response:

{
  "data": {
    "id": "run_01HQB...",
    "agentId": "agent_01HQA...",
    "status": "running",
    "createdAt": "2026-03-17T10:05:00.000Z"
  }
}

Save the run ID:

export RUN_ID="run_01HQB..."

---

Step 3: Check Run Results

Poll the run status until it completes, then retrieve the output:

cURL

curl -s "https://api.chainabit.com/api/v1/workspaces/$WORKSPACE_ID/ai/agents/$AGENT_ID/runs/$RUN_ID" \
  -H "Authorization: Bearer $TOKEN"

JavaScript

const res = await fetch(
  `https://api.chainabit.com/api/v1/workspaces/${WORKSPACE_ID}/ai/agents/${AGENT_ID}/runs/${RUN_ID}`,
  {
    headers: { Authorization: `Bearer ${TOKEN}` },
  },
);
const data = await res.json();
console.log(data);

Python

res = requests.get(
    f"{BASE}/workspaces/{WORKSPACE_ID}/ai/agents/{AGENT_ID}/runs/{RUN_ID}",
    headers={"Authorization": f"Bearer {TOKEN}"},
)
print(res.json())

Response:

{
  "data": {
    "id": "run_01HQB...",
    "agentId": "agent_01HQA...",
    "status": "completed",
    "output": {
      "summary": "You completed 4 out of 5 bits today. Highlights: Running streak extended to 7 days. Suggestion: Try adding a 5-minute meditation to your morning routine.",
      "completedBits": 4,
      "totalBits": 5
    },
    "tokensUsed": 284,
    "completedAt": "2026-03-17T10:05:12.000Z"
  }
}

---

Agent Lifecycle

---

Summary

In this tutorial you:

1. Created an AI agent definition in a workspace
2. Triggered an agent run with input parameters
3. Retrieved the run results after completion

Next Steps

• Chain Triggers to run chains (workflows) of agents on cron/event triggers
• Agents API Reference for the complete endpoint documentation