Summary

• Adds AgentCard model to agentex-sdk, enabling agents to describe their capabilities, lifecycle, and communication contract during registration
• Card is derived from existing code (StateWorkflow annotations + Pydantic models), not manually maintained config
• Flows through existing registration_metadata JSONB field — no server changes required

What changed

• New lib/types/agent_card.py — AgentCard, AgentLifecycle, LifecycleState models with from_state_machine() constructor and extract_literal_values() utility
• StateWorkflow — Added optional description, waits_for_input, accepts, transitions class attrs (all default to empty, no impact on existing agents)
• StateMachine — Added get_lifecycle() method to introspect registered workflows
• FastACP.create() — Accepts optional agent_card param
• register_agent() — Merges agent card into registration_metadata["agent_card"]

Backward compatibility

• All new fields are optional with safe defaults
• Verified 14 existing StateWorkflow subclasses across enterprise-emu, sgp-solutions, and tutorials — no conflicts
• registration_metadata preserves None when no agent_card or build info is present (existing behavior unchanged)
• Class hierarchy verified: SyncACP, AsyncBaseACP, TemporalACP all inherit _agent_card from BaseACPServer

Usage

Stateful agent:

from agentex.lib.sdk.state_machine import AgentCard

card = AgentCard.from_state_machine(
    state_machine=my_state_machine,
    output_event_model=MyOutputEventPayload,
    queries=["get_current_state"],
)
acp = FastACP.create(acp_type="agentic", agent_card=card, config=...)

Simple agent:

acp = FastACP.create(
    acp_type="sync",
    agent_card=AgentCard(input_types=["text"], data_events=["result"]),
)

Motivation

See design doc: agent-to-agent communication (OneEdge orchestrator ↔ specialized agents) requires a machine-readable contract per agent. Currently encoded as prose in LLM system prompts. Also enables TypeScript type codegen for frontend apps via output_schema (JSON Schema from Pydantic models).

🤖 Generated with Claude Code

Greptile Summary

Adds AgentCard — a Pydantic model that lets agents describe their capabilities, lifecycle states, and communication contract during registration. The card is derived from existing StateWorkflow annotations and Pydantic models (not manually maintained config), and flows through the existing registration_metadata JSONB field with no server-side changes required.

• New AgentCard, AgentLifecycle, LifecycleState models in agent_card.py with two constructors: from_states() (from a raw states list) and from_state_machine() (from a StateMachine instance)
• StateWorkflow gains optional class-level attributes (description, waits_for_input, accepts, transitions) with safe defaults
• StateMachine.get_lifecycle() introspects registered workflows for card construction
• FastACP.create() accepts optional agent_card param, threaded through to register_agent() which merges it into registration_metadata
• All changes are backward-compatible — new fields are optional with safe defaults
• Comprehensive test suite (396 lines) covering all new functionality

Important Files Changed

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A["FastACP.create(agent_card=card)"] --> B["Instance created<br/>(SyncACP / AsyncBaseACP / TemporalACP)"]
    B --> C["instance._agent_card = card"]
    C --> D["Lifespan startup"]
    D --> E["register_agent(env_vars, agent_card)"]
    E --> F{"agent_card is not None?"}
    F -- Yes --> G["card_data = agent_card.model_dump()"]
    G --> H["registration_metadata['agent_card'] = card_data"]
    F -- No --> I["registration_metadata = get_build_info()"]
    H --> J["POST /agents/register"]
    I --> J

    subgraph "AgentCard Construction"
        K["StateWorkflow subclasses<br/>(description, accepts, transitions)"] --> L["StateMachine.get_lifecycle()"]
        L --> M["AgentCard.from_state_machine()"]
        K --> N["State list + initial_state"]
        N --> O["AgentCard.from_states()"]
    end

This is a comment left during a code review.
Path: src/agentex/lib/sdk/state_machine/state_workflow.py
Line: 16-17

Comment:
**Mutable class-level list defaults are shared across subclasses**

`accepts` and `transitions` are mutable `list` objects defined at the class level. Any `StateWorkflow` subclass that does **not** override these attributes will share the exact same list object from the base class. If any code mutates these lists in-place at runtime (e.g., `workflow.accepts.append("video")`), it will silently corrupt all subclasses that inherit the default.

Today the code is safe because: (1) subclasses that care always override with a literal list, (2) `get_lifecycle` and `from_states` defensively copy with `list(...)`, and (3) no code mutates these in-place. However, using immutable defaults like tuples would make this structurally safe and prevent a future contributor from accidentally introducing a shared-state bug.

```suggestion
    accepts: tuple[str, ...] | list[str] = ()
    transitions: tuple[str, ...] | list[str] = ()
```

How can I resolve this? If you propose a fix, please make it concise.

_{Reviews (5): Last reviewed commit: "Add AgentCard.from_states() classmethod ..." | Re-trigger Greptile}