declare_agent()¶

Pre-register an AI agent with the Coalex platform. Call this at startup so the dashboard recognizes the agent before the first traces arrive. This sets up the merge key and lifecycle state for the agent.

Signature¶

PythonTypeScript

def declare_agent(
    *,
    agent_id: str,
    display_name: str | None = None,
    metadata: dict | None = None,
) -> AgentDeclaration

interface DeclareAgentOptions {
    agentId: string;
    displayName?: string;
    metadata?: Record<string, unknown>;
}

async function declareAgent(options: DeclareAgentOptions): Promise<AgentDeclaration>

Parameters¶

Parameter	Type	Default	Description
`agent_id`	`str`	required	Unique identifier for the agent. Must match the `agent_id` used in `coalex_context()`.
`display_name`	`str \\| None`	`None`	Human-readable name shown in the dashboard.
`metadata`	`dict \\| None`	`None`	Arbitrary key-value metadata to attach to the agent (e.g., team, owner, environment).

All parameters are keyword-only (enforced by *).

Requires register() first

declare_agent() uses the endpoint and API key configured by register(). Calling it before register() raises RuntimeError.

Returns¶

AgentDeclaration¶

PythonTypeScript

@dataclass(frozen=True)
class AgentDeclaration:
    agent_id: str
    lifecycle: str     # "active" | "staging" | "deprecated"
    created: bool      # True if newly created, False if already existed

interface AgentDeclaration {
    readonly agentId: string;
    readonly lifecycle: string;    // "active" | "staging" | "deprecated"
    readonly created: boolean;     // true if newly created
}

Field	Type	Description
`agent_id`	`str`	The agent identifier (mirrors the input parameter).
`lifecycle`	`str`	The agent's lifecycle state. One of `"active"`, `"staging"`, or `"deprecated"`.
`created`	`bool`	`True` if the agent was newly registered, `False` if it already existed.

Examples¶

Basic registration¶

PythonTypeScript

import coalex

coalex.register(endpoint="https://your-org.coalex.ai", api_key="your-key")

agent = coalex.declare_agent(
    agent_id="claims-processor",
    display_name="Claims Processor",
)
print(agent.lifecycle)  # "active"
print(agent.created)    # True (first time) or False (already registered)

import { register, declareAgent } from "@coalex-ai/sdk";

register({ endpoint: "https://your-org.coalex.ai", apiKey: "your-key" });

const agent = await declareAgent({
    agentId: "claims-processor",
    displayName: "Claims Processor",
});
console.log(agent.lifecycle);  // "active"
console.log(agent.created);    // true or false

With metadata¶

PythonTypeScript

agent = coalex.declare_agent(
    agent_id="underwriting-bot",
    display_name="Underwriting Bot",
    metadata={
        "team": "insurance",
        "owner": "alice@example.com",
        "environment": "production",
    },
)

const agent = await declareAgent({
    agentId: "underwriting-bot",
    displayName: "Underwriting Bot",
    metadata: {
        team: "insurance",
        owner: "alice@example.com",
        environment: "production",
    },
});

Notes¶

declare_agent() is idempotent -- calling it multiple times with the same agent_id is safe. The agent is created on the first call and returned as-is on subsequent calls.
The API endpoint used is POST /api/v1/agents.
Declaring agents before traces arrive ensures the dashboard shows the correct agent name and metadata from the start, rather than showing a raw agent_id.
Network errors from the Coalex API raise httpx.HTTPStatusError (Python) or Error (TypeScript).

API Reference¶

coalex.agents.declare_agent ¶

declare_agent(
    *,
    agent_id: str,
    display_name: str | None = None,
    metadata: dict | None = None,
    _config: CoalexConfig | None = None,
    _api_key: str | None = None,
) -> AgentDeclaration

Register or declare an agent before traces arrive.

This is the building block for lazy agent registration. When COA-264's set_prompt() is implemented, it will call this internally to ensure the agent exists.

Parameters:

Name	Type	Description	Default
`agent_id`	`str`	Unique agent identifier (the merge key).	required
`display_name`	`str \| None`	Optional human-friendly name.	`None`
`metadata`	`dict \| None`	Optional metadata (accepted but not persisted yet).	`None`
`_config`	`CoalexConfig \| None`	Override config (testing only).	`None`
`_api_key`	`str \| None`	Override API key (testing only).	`None`

Source code in coalex/agents.py

def declare_agent(
    *,
    agent_id: str,
    display_name: str | None = None,
    metadata: dict | None = None,
    _config: CoalexConfig | None = None,
    _api_key: str | None = None,
) -> AgentDeclaration:
    """Register or declare an agent before traces arrive.

    This is the building block for lazy agent registration.
    When COA-264's set_prompt() is implemented, it will call
    this internally to ensure the agent exists.

    Args:
        agent_id: Unique agent identifier (the merge key).
        display_name: Optional human-friendly name.
        metadata: Optional metadata (accepted but not persisted yet).
        _config: Override config (testing only).
        _api_key: Override API key (testing only).
    """
    import coalex as _sdk

    cfg = _config or _sdk._config
    api_key = _api_key or _sdk._api_key
    if cfg is None:
        raise RuntimeError("coalex.register() must be called before declare_agent()")

    payload: dict = {"agent_id": agent_id}
    if display_name is not None:
        payload["display_name"] = display_name
    if metadata is not None:
        payload["metadata"] = metadata

    with httpx.Client(timeout=30.0) as client:
        resp = client.post(
            f"{cfg.endpoint}/api/v1/agents",
            json=payload,
            headers={"Authorization": f"Bearer {api_key}"},
        )
        resp.raise_for_status()

    data = resp.json()
    return AgentDeclaration(
        agent_id=data["agent_id"],
        lifecycle=data["lifecycle"],
        created=data["created"],
    )