Create Component

Example catalog server

The component catalog requires the AgentOS-level database. Install the runtime and SQLite dependencies, then configure a shared API key:

uv pip install -U "agno[os]" sqlalchemy
export OS_SECURITY_KEY="your-agentos-key"

Save as catalog_api.py and run python catalog_api.py:

from agno.db.sqlite import SqliteDb
from agno.os import AgentOS

agent_os = AgentOS(db=SqliteDb(db_file="tmp/catalog-api.db"))
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="catalog_api:app", host="127.0.0.1", port=7777)

This creates a database catalog. It does not add or remove Python objects from an in-code agents, teams or workflows list. Use a supported synchronous BaseDb adapter with component methods.

Create a draft configuration:

curl --fail-with-body http://127.0.0.1:7777/components \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Reference Agent","component_type":"agent","stage":"draft","config":{"name":"Reference Agent","model":{"id":"gpt-5.4-mini","provider":"OpenAI"}}}'

Save the returned component_id; automatically generated IDs can include an owner suffix. This saves configuration, without validating provider credentials, invoking the model or deploying the component. Running this model later also requires its SDK and credentials.

Publication and access

On current main, the exposed set_current field is ignored. A draft does not set the published pointer; a published version becomes current even when set_current=false. Omit that field and choose the intended stage.

Published components can be readable across scoped owners. Writes remain owner-scoped, and draft preview requires separate authorization. A readable foreign or shared component can therefore still return 403 on a write.

POST/components

Create a new component (agent, team, or workflow) with initial config.

Authorization

HTTPBearer
AuthorizationBearer <token>

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl --request POST 'https://example.com/components' \  --header 'Content-Type: application/json' \  --data-raw '{"name":"string","component_type":"agent"}'
{  "component_id": "string",  "component_type": "agent",  "name": "string",  "user_id": "string",  "description": "string",  "current_version": 0,  "metadata": {},  "created_at": 0,  "updated_at": 0,  "deleted_at": 0}