Import Existing Agents

Convert agents from CrewAI, OpenAI, and other frameworks to agent.yaml

Why import

You have working agents. Rewriting them from scratch is a waste of time. Importing gives you:

• A standardized format that works across frameworks
• Schema validation that catches issues your current framework might not
• A path to multi-agent composition with agent-compose.yaml
• Portability — your agent definition is no longer locked to one framework

CrewAI walkthrough

Source file

Say you have a CrewAI agent defined in crewai-agent.yaml:

role: Technical Writer
goal: >
  Write clear, accurate technical documentation based
  on code analysis and team input.
backstory: >
  You are a technical writer with deep experience in
  developer documentation. You've written docs for APIs,
  SDKs, and developer tools at multiple companies.
llm: claude-sonnet-4-20250514
tools:
  - search_codebase
  - read_file
verbose: true
allow_delegation: false

Run the import

$ automagent import ./crewai-agent.yaml

The CLI auto-detects the CrewAI format (YAML file with role, goal, and backstory fields) and converts it.

Result

The generated agent.yaml:

apiVersion: v1
kind: agent

name: technical-writer
version: 0.1.0
description: Technical Writer # TODO: Review

model: claude-sonnet-4-20250514

instructions: |
  Goal: Write clear, accurate technical documentation based
  on code analysis and team input.

  Backstory: You are a technical writer with deep experience in
  developer documentation. You've written docs for APIs,
  SDKs, and developer tools at multiple companies.

tools:
  - name: search_codebase
  - name: read_file

extensions:
  crewai:
    role: Technical Writer
    verbose: true
    allow_delegation: false

What happened

OpenAI walkthrough

Source file

An OpenAI assistant exported as assistant.json:

{
  "name": "travel-planner",
  "instructions": "You are a travel planning assistant. Help users plan trips by suggesting destinations, creating itineraries, and finding deals. Always consider the user's budget and preferences.",
  "model": "gpt-4o",
  "tools": [
    { "type": "code_interpreter" },
    {
      "type": "function",
      "function": {
        "name": "search_flights",
        "description": "Search for available flights",
        "parameters": {
          "type": "object",
          "properties": {
            "origin": { "type": "string" },
            "destination": { "type": "string" },
            "date": { "type": "string" }
          },
          "required": ["origin", "destination", "date"]
        }
      }
    }
  ],
  "handoffs": [
    {
      "name": "booking-agent",
      "description": "Handles actual booking and payment"
    }
  ],
  "temperature": 0.7,
  "top_p": 0.9
}

Run the import

$ automagent import ./assistant.json -o travel-planner.yaml

Result

The generated travel-planner.yaml:

apiVersion: v1
kind: agent

name: travel-planner
version: 0.1.0
description: travel-planner # TODO: Review

model: gpt-4o

instructions: |
  You are a travel planning assistant. Help users plan trips by
  suggesting destinations, creating itineraries, and finding deals.
  Always consider the user's budget and preferences.

tools:
  - name: code_interpreter
  - name: search_flights
    description: Search for available flights
    inputSchema:
      type: object
      properties:
        origin:
          type: string
        destination:
          type: string
        date:
          type: string
      required:
        - origin
        - destination
        - date

dependencies:
  agents:
    - ref: booking-agent
      role: booking-agent

extensions:
  openai:
    tools:
      - type: code_interpreter
      - type: function
        function:
          name: search_flights
    temperature: 0.7
    top_p: 0.9

What happened

Tips after importing

Review TODO comments. Every imported file has at least one # TODO: Review comment, usually on the description field. Write a proper description — it is the first thing someone sees when browsing your agent.

Run validate. The import command runs validation automatically, but run it again after making edits:

$ automagent validate travel-planner.yaml

Check extensions. The extensions section preserves framework-specific fields. Review these to decide if any should be moved into standard fields or removed.

Pin your model. If the source used an unpinned alias like gpt-4, the validator will warn you. Consider pinning to a specific version for reproducible behavior.

Add guardrails and governance. The imported file captures what the agent does, but not what it shouldn’t do. Consider adding guardrails and governance sections to make your agent safer and more compliant.

See also

• automagent import — Full command reference
• Field reference — All available fields for enriching your imported agent
• automagent validate — Validate after editing