agent-contracts App Builder

Use this skill when you are implementing an AI agent using agent-contracts (not modifying the library itself).

Outcomes

• A working agent with well-defined state slices and node contracts
• CI-friendly validation (ContractValidator(strict=True) + agent-contracts validate --strict)
• Architecture docs (agent-contracts visualize) and contract change review (agent-contracts diff)

Workflow (recommended)

1. Start from a runnable baseline

- Use examples/05backendruntime.py as the default backend-shaped reference.

1. Design your state slices

- Keep request, response, internal as the core. - Add domain slices (e.g., ticket, orders, workflow) and register them via NodeRegistry.addvalid_slice(...).

1. Implement nodes contract-first

- Each node: NodeContract(name, description, reads, writes, supervisor, triggerconditions, requiresllm, services, is_terminal). - Keep writes=["request"] out of your design (discouraged).

1. Wire via registry + GraphBuilder

- Register nodes into a NodeRegistry. - Build with buildgraphfrom_registry(...), set entry point, compile.

1. Add runtime wrapper

- Use AgentRuntime (or StreamingRuntime when you need SSE-style progress events).

1. Make it safe to change

- Run ContractValidator(strict=True) in tests/CI. - Use agent-contracts diff to review breaking contract changes across versions. - Generate architecture docs with agent-contracts visualize.

Quick Checks

• Tests: pytest
• Coverage: pytest --cov=agent_contracts --cov-report=term-missing
• Contracts: agent-contracts validate --strict --module <your.nodes.module>
• Docs: agent-contracts visualize --module <your.nodes.module> --output ARCHITECTURE.md

Common Patterns

Backend request/response agent

• Use RequestContext + AgentRuntime for API handlers.
• Treat response.responsetype as your API “type”, and keep payload in response.responsedata.

Multi-step workflow

• Use a domain slice (e.g., workflow) + internal flags to drive steps (see examples/04multistepworkflow.py).

Interactive (question/answer) flow

• Use InteractiveNode for ask/process/check loops (see docs/core_concepts.md).

References (load only when needed)

• docs/getting_started.md
• docs/core_concepts.md
• docs/best_practices.md
• docs/cli.md
• examples/