Agent Forge CLI

CLI tool for syncing, versioning, and promoting agent configurations across staging and production environments.

Agent Forge is the CLI tool for managing agent configurations on the Amigo platform. It lets you create, update, version, and promote agent components programmatically rather than through the web interface.

What Agent Forge Does

Agent Forge treats agent configurations as code. You sync configurations to local JSON files, make changes, and push them back to the platform. This gives you version control, reproducibility, and the ability to script deployment workflows.

Agent Forge manages the following entity types:

• Agents: Persona, background, directives, and communication style

• Context graphs: Problem structure, states, transitions, and safety boundaries

• Dynamic behaviors: Runtime behaviors with triggers and response logic

• Metrics: Evaluation criteria and scoring rubrics

• Personas: Synthetic user profiles for simulation testing

• Scenarios: Test situations for simulation testing

• Unit test sets: Groups of tests with success criteria

Core Operations

Sync to Local

Pull configurations from the platform to your local file system:

# Pull all active agents
forge sync-to-local --entity-type agent --active-only

# Pull context graphs with a specific tag
forge sync-to-local --entity-type context_graph --tag emergency

# Pull evaluation framework components
forge sync-to-local --entity-type metric --tag accuracy
forge sync-to-local --entity-type persona --tag emergency_patient
forge sync-to-local --entity-type scenario --tag complex_symptoms

Sync to Remote

Push local changes back to the platform:

# Push all changes to staging
forge sync-to-remote --all --apply --env staging

# Push all changes to production
forge sync-to-remote --all --apply --env production

Before applying changes, Agent Forge shows exactly what will be modified so you can review before confirming.

Environment Support

Agent Forge supports separate staging and production environments. Changes are deployed to staging first, validated through testing, and then promoted to production.

agent-forge/
  local/
    staging/
      entity_data/
        agent/
        context_graph/
        dynamic_behavior_set/
        metric/
        persona/
        scenario/
        unit_test_set/
    production/
      entity_data/
        (same structure)

Typical Workflow

1. Pull current configurations from the platform to your local environment.

2. Make changes to the JSON configuration files.

3. Push to staging and run your test sets to validate.

4. Review results and iterate if tests fail.

5. Promote to production after validation passes.

This workflow supports both manual changes and automated optimization. Teams can use Agent Forge directly for planned configuration updates, or set up automated pipelines that use Agent Forge to deploy and test changes as part of a continuous improvement process.

When to Use Agent Forge

• Managing configurations across environments: Keep staging and production in sync with a controlled promotion process.

• Bulk updates: Modify multiple agents, behaviors, or evaluation criteria in a single operation.

• Scripted deployments: Integrate Agent Forge into CI/CD pipelines for automated testing and deployment.

• Audit and rollback: Maintain a complete history of configuration changes with the ability to revert.

For setup instructions and detailed CLI documentation, see the Agent Forge repository at https://github.com/amigo-ai/agent-forge.