CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Contribution workflow

• This repository is a Stainless-generated SDK. Open PRs against main; there is no next branch any more, and no label is needed. Merging the release-please PR publishes the release to PyPI.
• PR titles must follow Conventional Commits — the Validate PR title (Conventional Commits) CI check enforces this on every PR.
• Most of the SDK is generated, so API-surface changes belong in the API spec in scaleapi/scale-agentex (agentex/openapi.yaml), not in generated files. Hand-written code lives in src/agentex/lib/ and examples/.
• For maintainers: promote PRs open as drafts; approve them, never mark them ready or merge them, then, once checks are green, re-run the promote workflow. Merge a human PR into main only while staging main is an ancestor of production main and no codegen run is in flight, then run the back-sync (stlc-sync.yml in scaleapi/scale-agentex). Promote, then release, in one sitting. The runbook is at the top of .github/workflows/stlc-promote.yml in scaleapi/scale-agentex.
• See CONTRIBUTING.md for the full workflow.

Development Commands

Package Management in the top level repo

• Use rye for dependency management (preferred)
• Run ./scripts/bootstrap to set up the environment
• Or use rye sync --all-features directly

Special note: the individual tutorials maintain their own tutorial specific virtualenv using uv. So when testing/running tutorials, you uv run instead of rye run. Everything else is similar.

Testing

• Run tests: rye run pytest or ./scripts/test
• Run specific test: rye run pytest path/to/test_file.py::TestClass::test_method -v
• Mock server is automatically started for tests, runs on port 4010

Linting and Formatting

• Format code: rye run format or ./scripts/format
  • The repository is still in flux, so running format might accidentally change files that aren't part of your scope of changes. So always run run rye format with additional arguments to constrain the formatting to the files that you are modifying.
• Lint code: rye run lint or ./scripts/lint
• Type check: rye run typecheck (runs both pyright and mypy)

Building and Running

• Build package: rye build

CLI Commands

The package provides the agentex CLI with these main commands:

• agentex agents - Get, list, run, build, and deploy agents
• agentex tasks - Get, list, and delete tasks
• agentex secrets - Sync, get, list, and delete secrets
• agentex uv - UV wrapper with AgentEx-specific enhancements
• agentex init - Initialize new agent projects

Agent Development

• Run agents: agentex agents run --manifest manifest.yaml
• Debug agents: agentex agents run --manifest manifest.yaml --debug-worker
• Debug with custom port: agentex agents run --manifest manifest.yaml --debug-worker --debug-port 5679

Architecture Overview

Code Structure

• /src/agentex/ - Core SDK and generated API client code
• /src/agentex/protocol/ - Canonical location for wire-protocol shapes (JSON-RPC envelopes, ACP method-param types). Depends only on pydantic and the Stainless-generated agentex.types.* surface, so it is safe to import from a future slim REST-only install.
  • acp.py - RPCMethod, CreateTaskParams, SendMessageParams, SendEventParams, CancelTaskParams, RPC_SYNC_METHODS, PARAMS_MODEL_BY_METHOD
  • json_rpc.py - JSONRPCRequest, JSONRPCResponse, JSONRPCError
• /src/agentex/config/ - Canonical location for deployment/agent configuration models (manifest shapes). Depends only on pydantic, so it is safe to import from a slim REST-only install.
  • agent_config.py, build_config.py, deployment_config.py, local_development_config.py, environment_config.py, agent_manifest.py (model classes only), plus their model deps credentials.py and agent_configs.py
  • yaml loaders / build machinery (load_environments_config*, load_agent_manifest, build_context_manager, BuildContextManager) stay in agentex.lib.sdk.config.* so these models stay slim-safe
• /src/agentex/lib/ - Custom library code (not modified by code generator)
  • /cli/ - Command-line interface implementation
  • /core/ - Core services, adapters, and temporal workflows
  • /sdk/ - SDK utilities and FastACP implementation
    • config/ - manifest loaders + Docker build machinery (agent_manifest's load_agent_manifest/build_context_manager/BuildContextManager, validation, project_config) plus back-compat shims for the model classes now canonical under agentex.config.*
  • /types/ - Custom type definitions
    • acp.py, json_rpc.py - back-compat shims re-exporting from agentex.protocol.*. credentials.py, agent_configs.py - shims re-exporting from agentex.config.*. Existing from agentex.lib... imports keep working; new code should import from the canonical paths.
    • Other modules (tracing, agent_card, fastacp, llm_messages, converters, etc.) stay here — they have heavier transitive deps (temporal, openai-agents, model_utils/yaml) and aren't slim-safe.
  • /utils/ - Utility functions
• /examples/ - Example implementations and tutorials
• /tests/ - Test suites

Key Components

SDK Architecture:

• Client Layer: HTTP client for AgentEx API (_client.py, resources/)
• CLI Layer: Typer-based command interface (lib/cli/)
• Core Services: Temporal workflows, adapters, and services (lib/core/)
• FastACP: Fast Agent Communication Protocol implementation (lib/sdk/fastacp/)
• State Machine: Workflow state management (lib/sdk/state_machine/)

Temporal Integration:

• Workflow definitions in lib/core/temporal/
• Activity definitions for different providers
• Worker implementations for running temporal workflows

Agent Framework:

• Manifest-driven agent configuration
• Support for multiple agent types (sync, temporal-based)
• Debugging support with VS Code integration

Code Generation

Most SDK code is auto-generated. Manual changes are preserved in:

• src/agentex/lib/ directory
• examples/ directory
• Merge conflicts may occur between manual patches and generator changes

Key Dependencies

• temporalio - Temporal workflow engine
• typer - CLI framework
• pydantic - Data validation
• httpx - HTTP client
• fastapi - Web framework
• ruff - Linting and formatting
• pytest - Testing framework

Environment Requirements

• Python 3.12+ required
• Uses Rye for dependency management
• Supports both sync and async client patterns