Huu ni utafsiri wa mashine wa hati asili ya Kiingereza. Ikitokea mgongano wowote kati ya tafsiri hii na toleo asili la Kiingereza, toleo la Kiingereza ndilo litakalozingatiwa. Soma toleo asili la Kiingereza

API ya Umma

Caiioo inajumuisha REST API inayokuruhusu kudhibiti kila kitu kupitia programu: endesha mawakala, dhibiti zana, panga kazi, na zaidi. API inaishi kwenye seva hiyo hiyo ya ndani inayowezesha programu ya kompyuta na daraja la kivinjari.

URL ya Msingi: http://localhost:3847/v1

Uthibitishaji: Njia mbili za kuthibitisha, zote zikidhibitiwa na swichi ya API katika mipangilio:

Kwa watumiaji wa nje (skripti, miunganisho, curl): Weka tokeni ya ufikiaji wa API katika Mipangilio > Ufikiaji wa API, kisha itumie kama tokeni ya Bearer:

curl -H "Authorization: Bearer YOUR_API_TOKEN" http://localhost:3847/v1/providers

Kwa programu ya ndani (kiotomatiki): Programu ya kompyuta ya Caiioo, viendelezi vya kivinjari, na programu za simu huthibitisha kiotomatiki kupitia kichwa cha uthibitishaji cha relay kilichopo (X-Relay-Auth). Hakuna usanidi wa mwongozo unaohitajika — programu inashughulikia hili nyuma ya pazia.

Usanidi:

  1. Fungua Mipangilio ya Caiioo > Ufikiaji wa API
  2. Washa Washa API ya Umma
  3. Weka tokeni ya ufikiaji wa API (mfululizo wowote wa herufi unaochagua — ichukulie kama nywila)
  4. Tumia tokeni hiyo katika maombi yote ya API

API inapatikana kwenye localhost na kupitia relay ya kibinafsi. Angalia GET /v1/auth/info (hakuna uthibitishaji unaohitajika) kwa hali ya sasa na maelekezo ya usanidi.

Watoa Huduma na Modeli

Gundua ni watoa huduma gani wa LLM wamesanidiwa na ni modeli gani zinapatikana.

Orodhesha watoa huduma:

GET /v1/providers

Hurudisha aina zote za watoa huduma waliosanidiwa (Anthropic, OpenAI, Google, OpenRouter, Ollama, Poe, MLX, Baseten, na wengine wanapoongezwa) ikiwa na alama za uwezo (supportsVision, supportsToolCalling, supportsStreaming, n.k.) na ikiwa ufunguo wa API umesanidiwa.

Orodhesha modeli za mtoa huduma:

GET /v1/providers/anthropic/models

Hurudisha orodha ya modeli za mtoa huduma huyo. Kila modeli inajumuisha id, displayName, na contextLength inapopatikana.

Orodha ya pamoja ya watoa huduma wote:

GET /v1/models

Inaunganisha modeli kutoka kwa kila mtoa huduma aliyesanidiwa kuwa orodha moja. Watoa huduma wasio na funguo za API huachwa na kuorodheshwa kwenye warnings.

Mawakala

Mawakala ndio msingi wa caiioo. Kila wakala ni Njia — haiba iliyosanidiwa na maelekezo yake ya mfumo, zana, vigezo, na ujuzi.

Orodhesha mawakala wote:

GET /v1/agents

Inarudisha mawakala waliojengwa ndani (Shopping, Workplace, General) na mawakala wowote maalum uliounda. Kila mmoja amewekwa alama ya source: \"builtin\" au source: \"custom\".

Unda wakala maalum:

POST /v1/agents
Content-Type: application/json

{
  \"id\": \"my-research-agent\",
  \"branding\": {
    \"name\": \"Research Agent\",
    \"description\": \"Inatafuta kwenye wavuti na kufupisha matokeo\"
  },
  \"defaultSettings\": {
    \"systemPrompt\": \"Wewe ni msaidizi wa utafiti. Daima taja vyanzo.\",
    \"enabledTools\": { \"web_browsing\": true, \"search_tools\": true }
  },
  \"settingLevels\": {}
}

Inarudisha 201 pamoja na wakala aliyeundwa. Saa ya vekta inaunganishwa kiotomatiki kwa ajili ya usawazishaji.

Sasisha wakala:

PATCH /v1/agents/my-research-agent
Content-Type: application/json

{ \"branding\": { \"name\": \"Research Agent\", \"description\": \"Maelezo yaliyosasishwa\" } }

Inaunganisha kiraka kwenye wakala aliyepo na kuongeza saa ya vekta. Mawakala waliojengwa ndani wanarudisha 403 — ni wa kusoma tu.

Futa wakala:

DELETE /v1/agents/my-research-agent

Inafuta kwa njia ya muda (inasawazishwa kwenye vifaa). Inarudisha 204.

Kuendesha Maajenti

Hili ndilo tukio kuu — mwite ajenti ili kuchakata ujumbe.

Modi ya Uwiano (Synchronous)

Subiri jibu kamili:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "input": { "message": "Hali ya hewa ikoje Paris leo?" },
  "mode": "sync"
}

Hurudisha 200 ikiwa na { content, usage, status: "completed" } baada ya ajenti kumaliza. Ikiwa ajenti atapata hitilafu, hurudisha 500 ikiwa na { error, status: "error" }.

Modi Isiyo ya Uwiano (Asynchronous)

Tuma na uendelee — muhimu kwa kazi zinazochukua muda mrefu:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "my-research-agent",
  "input": { "message": "Andika uchambuzi wa maneno 2000 wa mienendo ya nishati mbadala" },
  "mode": "async"
}

Hurudisha 202 mara moja ikiwa na { runId, threadId, status: "running" }.

Ulizia hali:

GET /v1/runs/{runId}

Hurudisha { run: { runId, threadId, agentId, status, createdAt, content?, usage?, error? } }. Hali ni moja kati ya running, completed, error, au cancelled.

Tiririsha matukio kwa wakati halisi (SSE):

GET /v1/runs/{runId}/events

Hurudisha text/event-stream ikiwa na kila tukio la ajenti linapotokea: GENERATION_STARTED, STREAMING_CONTENT, miito ya zana, shughuli za ajenti mdogo, na tukio la mwisho (GENERATION_COMPLETE, GENERATION_ERROR, au GENERATION_CANCELLED). Mtiririko huisha baada ya tukio la mwisho.

Batilisha uendeshaji:

POST /v1/runs/{runId}/cancel

Hurudisha { run: { ..., status: "cancelled" } }.

Threads

Threads ni mazungumzo. Kila run ya agent hufanyika ndani ya thread, na threads huendelea kuwepo katika vipindi vyote (sessions). API inakuwezesha kuorodhesha, kusoma, kuunda, na kudhibiti threads kupitia programu.

Orodhesha threads zote (metadata pekee):

GET /v1/threads

Inarudisha threads za profile ya sasa huku ujumbe ukiwa umeondolewa kwa ajili ya utendaji wa haraka. Kila thread inajumuisha id, title, createdAt, updatedAt, modeId, archived, na takwimu za matumizi.

Pata thread ikiwa na ujumbe kamili:

GET /v1/threads/{id}

Inarudisha thread kamili ikijumuisha array yake ya messages — kila ujumbe wa mtumiaji, jibu la assistant, tool call, na matokeo ya tool.

Pata ujumbe pekee:

GET /v1/threads/{id}/messages

Inarudisha array ya messages pekee — nyepesi zaidi kuliko object kamili ya thread unapohitaji mazungumzo pekee.

Unda thread:

POST /v1/threads
Content-Type: application/json

{ "title": "Research project", "modeId": "general" }

Inarudisha 201 ikiwa na thread mpya. Kwa chaguo-msingi, API HAIBADILISHI thread inayotumika sasa kwenye app — weka "setActive": true kwenye body ikiwa unataka hilo. Thread mpya inaonekana kwenye sidebar mara moja (kupitia WebSocket broadcast).

Sasisha thread:

PATCH /v1/threads/{id}
Content-Type: application/json

{ "title": "Renamed project", "archived": true }

Sehemu zinazoweza kusasishwa: title, modeId, archived, lastUsedModel. Mabadiliko yanatangazwa kwenye sidebar kwa wakati halisi.

Futa thread:

DELETE /v1/threads/{id}

Inafuta thread kwa muda (tombstone kwa ajili ya sync). Inarudisha 204. Threads zilizofutwa huhamia kwenye trash na zinaweza kurejeshwa hadi trash itakapofutwa kabisa.

Thread inayotumika (Active thread):

GET /v1/threads/active            # Inarudisha { threadId }
PUT /v1/threads/active            # Body: { "threadId": "..." }

Usimamizi wa Trash:

GET /v1/threads/trash/count       # Inarudisha { count }
POST /v1/threads/trash/empty      # Inarudisha { deletedCount, protectedCount }

Threads zilizolindwa (zilizohifadhiwa kupitia kilelezo cha data retention) hazijumuishwi wakati wa kufuta trash.

Kuendeleza mazungumzo kupitia API: Ili kutuma ujumbe wa kufuatilia kwenye thread iliyopo, tumia POST /v1/runs ukiwa na ID ya thread:

POST /v1/runs
Content-Type: application/json

{
  "agentId": "general",
  "threadId": "existing-thread-id",
  "input": { "message": "Follow up on that last point" },
  "mode": "sync"
}

Agent huona historia nzima ya mazungumzo kutoka kwenye thread hiyo.

Viambatisho

Viambatisho ni faili zilizounganishwa kwenye nyuzi — picha za skrini, PDF, hati, picha zilizopakiwa, mabaki yaliyozalishwa. API inakuruhusu kuorodhesha, kupakia, kupakua, na kuvidhibiti.

Orodhesha viambatisho vyote (metadata pekee):

GET /v1/attachments

Hurudisha metadata ya kiambatisho kwa wasifu wa sasa. Mashamba mazito (dataUrl, extractedContent, extractedImages) yameondolewa — tumia sehemu za mwisho za maelezo au maudhui kwa ajili ya hayo.

Orodhesha viambatisho vya uzi maalum:

GET /v1/threads/{threadId}/attachments

Pata metadata ya kiambatisho:

GET /v1/attachments/{id}

Hurudisha metadata kamili ikiwa ni pamoja na extractedContent (maandishi ya OCR, markdown iliyochanganuliwa), contentType, fileName, size, na alama ya hasContent. Faili ghafi HAIJAJUMUISHWA — tumia sehemu ya mwisho ya /content kwa ajili hiyo.

Pakua faili ghafi ya kiambatisho:

GET /v1/attachments/{id}/content

Hurudisha faili ghafi ikiwa na vichwa sahihi vya Content-Type na Content-Disposition. Elekeza hii kwenye faili:

curl -o output.pdf \
  -H "Authorization: Bearer $API_TOKEN" \
  http://localhost:3847/v1/attachments/{id}/content

Pakia kiambatisho:

POST /v1/attachments
Content-Type: application/json

{
  "threadId": "thread-id",
  "type": "user_upload",
  "contentType": "application/pdf",
  "fileName": "report.pdf",
  "description": "Ripoti ya robo mwaka",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ..."
}

dataUrl ni URL ya data iliyosimbwa kwa base64. Hurudisha 201 ikiwa na kitambulisho kipya cha kiambatisho. Kiambatisho kinaunganishwa kwenye uzi uliotajwa.

Sasisha metadata ya kiambatisho:

PATCH /v1/attachments/{id}
Content-Type: application/json

{ "description": "Maelezo yaliyosasishwa", "fileName": "new-name.pdf" }

Futa kiambatisho:

DELETE /v1/attachments/{id}

Hufuta kwa njia ya muda. Hurudisha 204.

MCP Servers

Dhibiti miunganisho yako ya seva ya MCP (Model Context Protocol) — seva zinazowapa mawakala ufikiaji wa zana za nje na vyanzo vya data.

Orodhesha seva zilizosanidiwa:

GET /v1/mcp-servers

Inarudisha usanidi wote wa seva ya MCP kwa wasifu wa sasa. Sehemu nyeti (authToken, env, credentialId) huondolewa kwenye jibu.

Pata usanidi wa seva:

GET /v1/mcp-servers/{id}

Ongeza seva mpya ya MCP:

POST /v1/mcp-servers
Content-Type: application/json

{
  "id": "my-server",
  "name": "My MCP Server",
  "command": "npx",
  "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/files"],
  "serverType": "local"
}

Kwa seva za mbali za HTTP, tumia "url" badala ya "command":

{
  "id": "remote-server",
  "name": "Remote API",
  "url": "https://my-mcp-server.example.com/sse",
  "serverType": "remote"
}

Sasisha seva:

PATCH /v1/mcp-servers/{id}
Content-Type: application/json

{ "name": "Renamed Server", "args": ["-y", "@mcp/server-v2"] }

Washa/zima seva:

POST /v1/mcp-servers/{id}/toggle
Content-Type: application/json

{ "enabled": false }

Futa seva:

DELETE /v1/mcp-servers/{id}

Usimamizi wa Michakato (Process Management)

Kwa seva za ndani (stdio) za MCP, unaweza kudhibiti mchakato wa seva moja kwa moja.

Orodhesha michakato inayofanya kazi:

GET /v1/mcp-servers/processes

Inarudisha michakato ya seva inayofanya kazi ikiwa na pid, startedAt, na hali ya running.

Anzisha seva:

POST /v1/mcp-servers/{id}/start

Inasoma command/args/env kutoka kwenye usanidi wa seva na kuanzisha mchakato. Inarudisha hali ya mchakato.

Simamisha seva:

POST /v1/mcp-servers/{id}/stop

Inazima mchakato wa seva kwa usalama (SIGTERM ikifuatiwa na SIGKILL ikiwa ni lazima).

Ita mbinu ya JSON-RPC moja kwa moja:

POST /v1/mcp-servers/{id}/call
Content-Type: application/json

{ "method": "tools/list", "params": {} }

Inatuma ombi ghafi la JSON-RPC 2.0 kwenye seva na kurudisha matokeo. Ni muhimu kwa kutatua itilafu (debugging) au kuita mbinu ambazo hazijawekwa wazi kupitia API ya zana.

Zana na Mikoba ya Zana

Vinjari na uite zana ambazo mawakala huzitumia — kuvinjari wavuti, utafutaji, kalenda, Gmail, Slate, na zaidi.

Orodhesha mikoba ya zana (iliyopangwa):

GET /v1/toolkits

Hurudisha zana zilizojumuishwa zilizopangwa kwa kategoria (Tija, Utafutaji, Huduma, nk.) na seva zozote za MCP zilizounganishwa kama mikoba tofauti ya zana, kila moja ikiwa na vitendo vyake vilivyoorodheshwa.

Orodhesha zana zote:

GET /v1/tools
GET /v1/tools?source=embedded   # Zana za ndani pekee
GET /v1/tools?source=mcp        # Zana za seva ya MCP pekee

Pata maelezo ya zana na mpangilio wa ingizo:

GET /v1/tools/calculator

Hurudisha JSON Schema ya zana kwa ajili ya vigezo vyake vya ingizo, ili uweze kuthibitisha kabla ya kuita.

Ite zana moja kwa moja:

POST /v1/tools/calculator/invoke
Content-Type: application/json

{ "input": { "expression": "sqrt(144) + 3^2" } }

Hurudisha { result }. Ingizo linathibitishwa dhidi ya schema ya zana — ingizo batili hurudisha 422 ikiwa na maelezo. Zana za mbali za MCP hurudisha 501 zikiwa na mwongozo wa kutumia /v1/runs badala yake (zinahitaji usafirishaji wa mchakato mdogo wa wakala).

Viunganishi

Dhibiti miunganisho ya OAuth — Google, Microsoft, GitHub, Notion, Slack, na zaidi.

Vinjari miunganisho inayopatikana:

GET /v1/connectors/catalog

Hurudisha watoa huduma wote wa OAuth waliosajiliwa wakiwa na majina yao, kategoria, na upeo wa msingi.

Orodhesha akaunti zako zilizounganishwa:

GET /v1/connectors

Hurudisha miunganisho inayofanya kazi kwa wasifu wa sasa. Tokeni hazionyeshwi kamwe — ni metadata pekee (mtoa huduma, barua pepe, hali, upeo, alama za muda).

Angalia afya ya muunganisho:

POST /v1/connectors/{id}/test

Hurudisha { health: { status, isTokenExpired, canRefresh } }.

Ondoa muunganisho:

DELETE /v1/connectors/{id}

Kuunda miunganisho mipya kunahitaji mchakato mwingiliano wa OAuth kupitia UI ya programu au njia za /auth/*.

Vichochezi

Panga mawakala kujiendesha otomatiki — muhtasari wa kila siku, ripoti za kila wiki, ufuatiliaji wa mara kwa mara.

Orodhesha vichochezi:

GET /v1/triggers

Unda kichochezi kilichopangwa:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Muhtasari wa Asubuhi",
  "prompt": "Fanya muhtasari wa barua pepe zangu ambazo hazijasomwa na kalenda ya leo",
  "modeId": "general",
  "schedule": { "type": "daily", "time": "08:00" }
}

Aina za ratiba zinazotumika:

  • { "type": "interval", "minutes": 60 } — kila baada ya dakika N (min 15, max 1440)
  • { "type": "daily", "time": "09:00" } — kila siku kwa muda maalum
  • { "type": "weekly", "day": "mon", "time": "09:00" } — kila wiki
  • { "type": "weekdays", "time": "08:30" } — Jumatatu hadi Ijumaa
  • { "type": "daysOfWeek", "days": ["mon", "wed", "fri"], "time": "10:00" } — siku maalum
  • { "type": "monthly", "dayOfMonth": 1, "time": "09:00" } — kila mwezi
  • { "type": "manual" } — pale tu inapochochewa kupitia API

Chochea kichochezi kwa mwongozo:

POST /v1/triggers/{id}/fire

Hurudisha 202 ikiwa na threadId kwa ajili ya uendeshaji unaotokana.

Sasisha au futa:

PATCH /v1/triggers/{id}
DELETE /v1/triggers/{id}

Webhooks

Vichochezi vya Webhook huruhusu huduma za nje (CI/CD, ufuatiliaji, wajenzi wa fomu) kuchochea uendeshaji wa wakala kupitia HTTP.

Unda kichochezi cha webhook:

POST /v1/triggers
Content-Type: application/json

{
  "name": "Deploy hook",
  "prompt": "Usambazaji umetokea: {{webhook.body}}",
  "modeId": "general",
  "kind": "webhook"
}

Hurudisha 201 ikiwa na webhookSecret na webhookPath. Hifadhi siri hiyo — utaihitaji ili kusaini mizigo ya data.

Tuma webhook:

# Kokotoa HMAC-SHA256 ya mwili ghafi wa ombi
SIGNATURE=$(echo -n '{"repo":"my-app","branch":"main"}' | openssl dgst -sha256 -hmac "$WEBHOOK_SECRET" | awk '{print $2}')

POST /v1/webhooks/{triggerId}
Content-Type: application/json
X-Webhook-Signature: $SIGNATURE

{"repo": "my-app", "branch": "main"}

Sehemu ya mwisho ya webhook HAIHITAJI uthibitishaji wa bearer — inatumia uhakiki wa HMAC badala yake. Hurudisha 202 ikiwa na threadId ya uendeshaji uliotumwa. Kishika nafasi cha {{webhook.body}} katika maelekezo ya kichochezi hubadilishwa na mwili ghafi wa ombi.

Kazi Maalum

Unda zana zako mwenyewe ambazo mawakala wanaweza kuziita. Kazi huandikwa kwa JavaScript au Python na huendeshwa katika mazingira yaliyotengwa (sandbox).

Orodhesha kazi:

GET /v1/functions

Unda kazi:

POST /v1/functions
Content-Type: application/json

{
  "name": "calculate_bmi",
  "description": "Kokotoa Kielezo cha Uzito wa Mwili (BMI) kutoka kwenye urefu na uzito",
  "language": "javascript",
  "source": "return { bmi: (input.weightKg / (input.heightM * input.heightM)).toFixed(1) };",
  "inputSchema": {
    "type": "object",
    "properties": {
      "weightKg": { "type": "number" },
      "heightM": { "type": "number" }
    },
    "required": ["weightKg", "heightM"]
  }
}

Kazi za JavaScript hupokea input na lazima zirudishe matokeo. Kazi za Python huweka kigezo cha result:

# Mfano wa Python
result = {"bmi": round(input["weightKg"] / (input["heightM"] ** 2), 1)}

Tekeleza kazi moja kwa moja:

POST /v1/functions/{id}/execute
Content-Type: application/json

{ "input": { "weightKg": 75, "heightM": 1.80 } }

Usalama: JavaScript huendeshwa katika sandbox ya vm ya Node (hakuna ufikiaji wa mfumo wa faili au mtandao, kikomo cha muda cha sekunde 10). Python huendeshwa kama mchakato mdogo wenye kikomo cha muda cha sekunde 30. Zote mbili huthibitisha ingizo kabla ya utekelezaji.

Sasisha au futa:

PATCH /v1/functions/{id}
DELETE /v1/functions/{id}

Mitiririko ya Kazi

Panga mawakala wengi katika DAG (directed acyclic graph) — endesha hatua kwa sambamba inapowezekana, na lisha matokeo kutoka hatua za awali kwenda hatua za baadaye.

Thibitisha grafu ya mtiririko wa kazi:

POST /v1/workflows/validate
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Tafiti mienendo ya nishati mbadala" },
      { "id": "analyze", "agentId": "general", "prompt": "Tafiti bei za washindani" },
      { "id": "report", "agentId": "general", "prompt": "Andika ripoti inayounganisha: {{outputs.research}} na {{outputs.analyze}}", "dependsOn": ["research", "analyze"] }
    ]
  }
}

Hurudisha { valid: true/false, errors: [...] }. Hukagua mizunguko, vitambulisho vilivyojirudia, na marejeleo ya utegemezi yanayokosekana.

Tekeleza mtiririko wa kazi:

POST /v1/workflows/execute
Content-Type: application/json

{
  "graph": {
    "nodes": [
      { "id": "research", "agentId": "general", "prompt": "Tafiti mienendo ya nishati mbadala" },
      { "id": "summarize", "agentId": "general", "prompt": "Fanya muhtasari wa: {{outputs.research}}", "dependsOn": ["research"] }
    ]
  }
}

Hurudisha { status: "completed", outputs: { research: "...", summarize: "..." }, nodeResults: {...} }.

Nodi zinazojitegemea (zisizo na utegemezi wa pamoja) huendeshwa kwa sambamba. Kishika nafasi cha {{outputs.nodeId}} katika maelekezo ya nodi hubadilishwa na matokeo ya maudhui ya nodi ya juu iliyotajwa. Kila nodi ni uendeshaji kamili wa wakala, hivyo inaweza kutumia zana, kuvinjari wavuti, na kufikia uwezo wote wa wakala lengwa.

Kanzi za Maarifa

Panga nyaraka katika makusanyo yanayoweza kutafutwa ambayo mawakala wanaweza kuyarejelea.

Orodhesha kanzi za maarifa:

GET /v1/knowledge/bases

Unda kanzi ya maarifa:

POST /v1/knowledge/bases
Content-Type: application/json

{ "name": "Makala za Utafiti" }

Hurudisha 201 ikiwa na kitambulisho kipya cha kanzi.

Pakia hati kwenye kanzi ya maarifa:

POST /v1/knowledge/bases/{id}/documents
Content-Type: application/json

{
  "fileName": "research-paper.pdf",
  "contentType": "application/pdf",
  "dataUrl": "data:application/pdf;base64,JVBERi0xLjQ...",
  "description": "Mienendo ya nishati mbadala 2026"
}

Uwanja wa dataUrl ni URL ya data iliyosimbwa kwa base64. Hurudisha 201 ikiwa na metadata ya hati.

Orodhesha hati katika kanzi ya maarifa:

GET /v1/knowledge/bases/{id}/documents

Tafuta ndani ya kanzi ya maarifa:

POST /v1/knowledge/bases/{id}/search
Content-Type: application/json

{ "query": "nishati mbadala" }

Hurudisha hati zinazolingana kulingana na jina la faili na maelezo. Utafutaji wa kisemantiki (vekta) unakuja katika toleo lijalo.

Futa hati au kanzi ya maarifa:

DELETE /v1/knowledge/bases/{id}/documents/{docId}
DELETE /v1/knowledge/bases/{id}

Hamisha na Ingiza Mawakala

Shiriki mawakala kama vifurushi vinavyobebeka — kwenye vifaa, timu, au Community Hub.

Hamisha wakala:

POST /v1/agents/{id}/export

Inarudisha kifurushi cha JSON chenye ufafanuzi wa wakala, mahitaji ya zana (yaliyotokana na zana zilizowashwa), mahitaji ya kiunganishi (ni watoa huduma gani wa OAuth wanahitajika), na templeti za vichochezi. Metadata ya usawazishaji inaondolewa — kifurushi ni ramani safi inayojitegemea.

Ingiza wakala:

POST /v1/agents/import
Content-Type: application/json

{
  \"package\": {
    \"$schema\": \"caiioo.agent.package/v1\",
    \"agent\": {
      \"id\": \"shared-research-agent\",
      \"branding\": { \"name\": \"Research Agent\", \"description\": \"Kutoka kwa timu\" },
      \"defaultSettings\": { \"systemPrompt\": \"Unafanya utafiti wa mambo.\" },
      \"settingLevels\": {}
    },
    \"toolRequirements\": [
      { \"toolId\": \"web_browsing\", \"enabled\": true },
      { \"toolId\": \"search_tools\", \"enabled\": true }
    ]
  }
}

Inarudisha 201 pamoja na wakala aliyesakinishwa. Migongano ya ID na mawakala waliojengwa ndani au waliopo inarudisha 409.

Kushughulikia Hitilafu

API inatumia misimbo ya hali ya kawaida ya HTTP:

Msimbo Maana
200 Mafanikio
201 Imeundwa
202 Imekubaliwa (shughuli isiyo ya kusubiri imeanza)
204 Imefutwa (hakuna maudhui)
400 Ombi baya — kagua uwanja wa error kwa maelezo
401 Huna idhini — siri ya kikao inakosekana au si sahihi
403 Imekatazwa — k.m., kujaribu kurekebisha wakala wa ndani
404 Haikupatikana
409 Mgongano — k.m., kitambulisho cha wakala tayari kipo
422 Hitilafu ya uthibitishaji — ingizo halilingani na schema ya zana
500 Hitilafu ya seva — kagua uwanja wa error
501 Haijatekelezwa — kipengele kipo lakini hakipatikani kwa njia hii
503 Huduma haipatikani — hifadhi au mtoa huduma hayuko tayari

Majibu yote ya hitilafu yanajumuisha { "error": "ujumbe unaosomwa na binadamu" }.

Mfano wa Kuanza Haraka

Huu hapa ni mtiririko kamili wa kazi: unda wakala, uendeshe, na utiririshe matokeo.

# 1. Unda wakala maalum
curl -X POST http://localhost:3847/v1/agents \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "quick-summarizer",
    "branding": { "name": "Quick Summarizer" },
    "defaultSettings": {
      "systemPrompt": "Fanya muhtasari wa ingizo lolote kwa ufupi katika nukta 3.",
      "enabledTools": { "web_browsing": true }
    },
    "settingLevels": {}
  }'

# 2. Uendeshe bila kusubiri
RUN=$(curl -s -X POST http://localhost:3847/v1/runs \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "agentId": "quick-summarizer", "input": { "message": "Summarize https://en.wikipedia.org/wiki/Artificial_intelligence" }, "mode": "async" }')

RUN_ID=$(echo $RUN | jq -r '.runId')

# 3. Tiririsha matukio
curl -N http://localhost:3847/v1/runs/$RUN_ID/events \
  -H "Authorization: Bearer $API_TOKEN"

# 4. Hamisha wakala kwa ajili ya kushiriki
curl -X POST http://localhost:3847/v1/agents/quick-summarizer/export \
  -H "Authorization: Bearer $API_TOKEN"

This guide is maintained by the Caiioo team using Slate, our built-in editor.