declare_agent()

Pre-register an AI agent with the Coalex platform. This is optional but recommended — calling it at startup ensures the dashboard recognizes the agent before the first traces arrive and sets up the merge key and lifecycle state.

---

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(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({ 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"],
    )