Skip to Content
Aegis Enterprise
DocumentationAgent CoreAgent Core Tutorial

Aegis Agents API Tutorial

Introduction

Aegis leverages Autogen agents to automate complex workflows using AI-driven decision-making. The Aegis Agents API provides a structured way to deploy and execute these agents in a production environment.

Key Concepts

  • Tasks: Define what needs to be accomplished.
  • Teams: A logical grouping of agents that collaborate on a task (based on Autogen Teams).
  • Sessions: A container for runs that provides contextual continuity by linking tasks with teams.
  • Runs: Individual executions of an Autogen Team to solve a task within a session.

This tutorial will guide you through setting up an Automarking Task, configuring a Team, starting a Session, and executing a Run using the Aegis API. Automarking is just an example; the API is capable of running various AI-driven workflows.

Step 1: Create a Task

To create an Automarking Task, send the following request:

POST /api/v1/task
{
  "name": "Automarking Task",
  "description": "Evaluate student responses for correctness.",
  "version": "1.0.0",
  "created_by_user_id": "<user_id>"
}

Response:

{
  "message": "Task created.",
  "data": {
    "id": "<task_id>",
    "name": "Automarking Task",
    "description": "Evaluate student responses for correctness."
  }
}

Step 2: Create a Team

A Team consists of one or more agents that collaborate to complete a task. Below is an example of a Automarking Assistant agent:

Note: The JSON input and output formats for the Team Runs API are specified in the Team configuration (config). These formats are fully customizable to match any valid JSON schema supported by the underlying OpenAI or other LLM APIs. Frontend clients should not assume these formats are fixed but instead can configure them as required.

See notebooks/tutorial.ipynb to create your own Team configuration.

POST /api/v1/team
{
  "component": {
    "provider": "autogen_agentchat.agents.AssistantAgent",
    "component_type": "agent",
    "version": 1,
    "component_version": 1,
    "description": "An agent that provides assistance with tool use.",
    "label": "AssistantAgent",
    "config": {
      "name": "structured_agent",
      "model_client": {
        "provider": "autogen_ext.models.openai.OpenAIChatCompletionClient",
        "component_type": "model",
        "version": 1,
        "component_version": 1,
        "description": "Chat completion client for OpenAI hosted models.",
        "label": "OpenAIChatCompletionClient",
        "config": {
          "model": "gpt-4o-mini"
        }
      },
      "tools": [],
      "workbench": {
        "provider": "autogen_core.tools.StaticWorkbench",
        "component_type": "workbench",
        "version": 1,
        "component_version": 1,
        "description": "A workbench that provides a static set of tools that do not change after\n    each tool execution.",
        "label": "StaticWorkbench",
        "config": {
          "tools": []
        }
      },
      "model_context": {
        "provider": "autogen_core.model_context.UnboundedChatCompletionContext",
        "component_type": "chat_completion_context",
        "version": 1,
        "component_version": 1,
        "description": "An unbounded chat completion context that keeps a view of the all the messages.",
        "label": "UnboundedChatCompletionContext",
        "config": {}
      },
      "description": "An agent that provides assistance with ability to use tools.",
      "system_message": "\nYou are an assessment assistant evaluating student responses.\n\nYou will be given:\n- A **question**\n- A **model answer** that reflects what a good answer should include\n- A **student answer**\n\nYour task is to evaluate the student answer using the following criteria:\n\n1. **Relevance Score**: Rate how relevant the student\u2019s answer is to the question, an integer from 1 (not relevant) to 5 (fully relevant).\n2. **Completeness Score**: Rate how complete the student\u2019s answer is, an integer from 1 (missing key parts) to 5 (fully complete).\n3. **Reasoning**: Think step-by-step and explain your evaluation. If the task is ambiguous or judgment is difficult, include that in your reasoning.\n4. **Satisfactory**: Set to true if the student answer meets minimum requirements.\n5. **Confidence Score**: Rate your own confidence in the evaluation, an integer from 0 (not confident) to 10 (very confident). If your reasoning was clear and deterministic, confidence should be high. If it was ambiguous or complex, reduce confidence accordingly.\n\nRespond ONLY in the following JSON format:\n\n```json\n{\n  \"relevance\": 4,\n  \"completeness\": 5,\n  \"reasoning\": \"Explain your decision here...\",\n  \"satisfactory\": true/false,\n  \"confidence\": 8\n}\n",
      "model_client_stream": false,
      "reflect_on_tool_use": true,
      "tool_call_summary_format": "{result}",
      "metadata": {},
      "structured_message_factory": {
        "provider": "autogen_agentchat.messages.StructuredMessageFactory",
        "component_type": "structured_message",
        "version": 1,
        "component_version": 1,
        "description": ":meta private:",
        "label": "StructuredMessageFactory",
        "config": {
          "json_schema": {
            "properties": {
              "completeness": {
                "title": "Completeness",
                "type": "integer"
              },
              "relevance": {
                "title": "Relevance",
                "type": "integer"
              },
              "reasoning": {
                "title": "Reasoning",
                "type": "string"
              },
              "satisfactory": {
                "title": "Satisfactory",
                "type": "boolean"
              },
              "confidence": {
                "title": "Confidence",
                "type": "integer"
              }
            },
            "required": [
              "completeness",
              "relevance",
              "reasoning",
              "satisfactory",
              "confidence"
            ],
            "title": "OutputModel",
            "type": "object"
          },
          "content_model_name": "OutputModel"
        }
      }
    }
  },
  "structured_input": {
    "provider": "autogen_agentchat.messages.StructuredMessageFactory",
    "component_type": "structured_message",
    "version": 1,
    "component_version": 1,
    "description": ":meta private:",
    "label": "StructuredMessageFactory",
    "config": {
      "json_schema": {
        "properties": {
          "question": {
            "title": "Question",
            "type": "string"
          },
          "model_answer": {
            "title": "Model Answer",
            "type": "string"
          },
          "learner": {
            "title": "Learner",
            "type": "string"
          }
        },
        "required": ["question", "model_answer", "learner"],
        "title": "InputModel",
        "type": "object"
      },
      "format_string": "**Question:**\n\n{question}\n\n**Model Answer**:\n\n {model_answer}\n\n**Student Answer**:\n\n {learner}",
      "content_model_name": "InputModel"
    }
  },
  "version": "0.0.1"
}

Response:

{
  "message": "Team created.",
  "data": {
    "id": "<team_id>",
    "component": <team_component>
  }
}

Step 3: Create a Session

A Session groups multiple runs of a task and ensures continuity. Create a session linked to the Automarking Task and Team:

POST /api/v1/session
{
  "task_id": "<task_id>",
  "team_id": "<team_id>",
  "created_by_user_id": "<user_id>",
  "archived": false,
  "team_metadata": {}
}

Response:

{
  "message": "Session created.",
  "data": {
    "id": "<session_id>",
    "task_id": "<task_id>",
    "team_id": "<team_id>"
  }
}

Step 4: Create a Run

A Run represents a single execution of a task within a session. Here’s how to start an Automarking Run:

POST /api/v1/run
{
  "session_id": "<session_id>",
  "task_id": "<task_id>",
  "run_task": {
    "source": "string",
    "content": {
      "question": "Name 3 capital cities in Australia.",
      "model_answer": "3 out of Canberra, Sydney, Melbourne, Perth, Adelaide, Brisbane, Darwin, Hobart",
      "learner": "Canberra, Syney, Melbourne"
    },
    "message_type": "dict"
  },
  "batch_mode": false
}

Response:

{
  "message": "Run created.",
  "meta": {},
  "data": {
    "session_id": "<session_id>",
    "task_id": "<task_id>",
    "run_task": {
      "source": "string",
      "content": {
        "question": "A",
        "model_answer": "B"
      },
      "message_type": "dict"
    },
    "created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "archived": false,
    "id": "<run_id>",
    "messages": []
  }
}

Response:

{
  "message": "Run created.",
  "meta": {},
  "data": {
    "session_id": "<session_id>",
    "task_id": "<task_id>",
    "run_task": {
      "source": "string",
      "content": {
        "question": "A",
        "model_answer": "B"
      },
      "message_type": "dict"
    },
    "batch_mode": false,
    "created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "archived": false,
    "id": "<run_id>",
    "messages": []
  }
}

Step 5: Retrieve Results

You can retrieve runs like this:

GET /api/v1/run/<run_id>

Example Response:

{
  "message": "Data got correctly",
  "meta": {},
  "data": {
    "session_id": "0195c641-0d8e-7061-a65b-79051d4929ca",
    "task_id": "0195c63e-e1ca-7751-9721-84b4b8d310ee",
    "run_task": {
      "source": "string",
      "content": {
        "question": "A",
        "model_answer": "B"
      },
      "message_type": "dict"
    },
    "batch_mode": false,
    "created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "archived": false,
    "id": "0195c6b9-5c97-796b-aa06-2a267d7d328e",
    "status": "complete",
    "team_result": {
      "task_result": {
        "messages": [
          {
            "source": "automarking_agent",
            "content": {
              "reasoning": "The student correctly identified Canberra, Sydney and Melbourne.",
              "satisfactory": true,
              "relevance_score": 10,
              "completeness_score": 10,
              "confidence_score": 0.9
            },
            "type": "dict"
          }
        ],
        "stop_reason": null
      }
    },
    "error_message": null,
    "created_at": "2025-03-24T05:56:31.511798Z",
    "estimated_completion_time": null
  }
}

Error Testing with Stub Sequences

NOTE: This Section is only available if you are using the Aegis Enterprise version.

The Aegis Agents API supports simulated error testing via a special stub model: stub_error_sequence. This model is designed to sequentially raise errors from LiteLLM’s supported exception types, enabling robust error handling and observability testing in your application.

Supported Errors

A predefined sequence includes the full set of LiteLLM exception types. Refer to the official docs for details:

🔗 LiteLLM Exception Mapping Documentation 

Simulate Errors Using Agent Runs

1. Create a Session with the stub_error_sequence Model

To simulate errors, create a session using team_metadata.model = "stub_error_sequence".

POST /api/v1/session
{
  "task_id": "<task_id>",
  "team_id": "<team_id>",
  "created_by_user_id": "<user_id>",
  "archived": false,
  "team_metadata": {
    "model": "stub_error_sequence"
  }
}

2. Create Runs to Trigger Each Error in the Sequence

Each time you create a run, the stub model will raise the next error from the sequence. So you are able to cycle through all the error messages you will see.

POST /api/v1/run
{
  "session_id": "<session_id>",
  "task_id": "<task_id>",
  "run_task": {
    "source": "test",
    "content": {
      "question": "trigger error"
    },
    "message_type": "dict"
  },
  "created_by_user_id": "<user_id>"
}

The error will be logged in the run’s metadata:

{
  "status": "error",
  "error_message": "litellm.RateLimitError: You've hit the rate limit",
  "error_details": {
    "type": "RateLimitError",
    "message": "...",
    "status_code": 429,
    "llm_provider": "openai",
    "model": "stub_error_sequence"
  }
}

Use this feature to test how your system handles retries, logs errors, and populates dashboards.

Batch Runs

The Aegis Agents API supports batch processing for executing multiple runs simultaneously. For Batch processing, one can use the BatchOpenAI client if the agent is just required to run a single LLM query. Alterenatively, celery tasks are used to execute muliple LLM calls in the background which are grouped together in the batch query response. The batch API is very similar to the run API with one primary difference - the run_task is now a dictionary with the key being a unique ID for an individual query and the value being the run_task of a single run.

Creating a Batch Run

Initially, when a batch run is created, the response will include the batch run ID and an initial status of created. Results will not be available immediately and must be fetched separately.

Example API Call to Create a Batch Run

POST /api/v1/batch_run

Request:

{
  "session_id": "<session_id>",
  "task_id": "<task_id>",
  "run_task": {
    "custome_id_1": {
      "source": "string",
      "content": {
        "question": "Name 3 capital cities in Australia.",
        "model_answer": "3 out of Canberra, Sydney, Melbourne, Perth, Adelaide, Brisbane, Darwin, Hobart",
        "learner": "Canberra, Syney, Melbourne"
      },
      "message_type": "dict"
    },
    "custom_id_2": {
      "source": "string",
      "content": {
        "question": "Name 3 capital cities in Australia.",
        "model_answer": "3 out of Canberra, Sydney, Melbourne, Perth, Adelaide, Brisbane, Darwin, Hobart",
        "learner": "Canberra, Syney, Melbourne"
      },
      "message_type": "dict"
    }
  }
}

Initial Response (Batch Creation)

{
  "message": "Batch run created.",
  "data": {
    "id": "<batch_run_id>",
    "status": "created",
    "created_at": "2025-03-24T05:56:31.511798Z"
  }
}

Retrieving Batch Run Results

Before, retriving a batch result, the user must query batch_status to check if the processing if batch processing is complete. The query, runs a batch retrival process and updates the state of the batch. If the batch processing is complete, then the user is able to retrieve the batch results. To retrieve the status and results of the batch run, perform a GET request using the batch run ID.

GET /api/v1/run/<batch_run_id>

If the batch run is still processing (status: active), the response will include the current status without detailed results:

{
  "message": "Batch run is currently active.",
  "data": {
    "id": "<batch_run_id>",
    "session_id": "<session_id>",
    "task_id": "<task_id>",
    "status": "active",
    "created_at": "2025-03-24T05:56:31.511798Z",
    "estimated_completion_time": "2025-03-24T06:01:31.511798Z"
  }
}

Once the batch run completes (status: complete), detailed results will be available:

{
  "message": "Data got correctly",
  "meta": {},
  "data": {
    "session_id": "0195c641-0d8e-7061-a65b-79051d4929ca",
    "task_id": "0195c63e-e1ca-7751-9721-84b4b8d310ee",
    "run_task": {
      "source": "string",
      "content": {
        "question": "A",
        "model_answer": "B"
      },
      "message_type": "dict"
    },
    "batch_mode": false,
    "created_by_user_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "archived": false,
    "id": "0195c6b9-5c97-796b-aa06-2a267d7d328e",
    "status": "complete",
    "team_result": {
      "custom_id_1": {
        "task_result": {
          "messages": [
            {
              "reasoning": "The student identified Canberra and Sydney correctly, but Brisbane is incorrect.",
              "satisfactory": false,
              "relevance_score": 8,
              "completeness_score": 7,
              "confidence_score": 0.85
            }
          ],
          "stop_reason": null
        }
      },
      "custom_id_2": {
        "task_result": {
          "messages": [
            {
              "reasoning": "The student correctly identified Paris.",
              "satisfactory": true,
              "relevance_score": 10,
              "completeness_score": 10,
              "confidence_score": 0.95
            }
          ],
          "stop_reason": null
        }
      }
    },
    "error_message": null,
    "created_at": "2025-03-24T05:56:31.511798Z",
    "estimated_completion_time": null,
    "batch_mode": true,
    "status": "complete"
  }
}

The batch run status can be one of the following:

  • created
  • active
  • complete
  • error
  • stopped

You can periodically poll the endpoint to monitor the progress and fetch the results of the batch run.

Conclusion

This tutorial demonstrated how to:

  • Create a Task
  • Configure a Team
  • Start a Session
  • Execute a Run
  • Retrieve Results
  • Test Error Handling with Stub Sequences

With the Aegis Agents API, you can build scalable, production-ready AI workflows using Autogen Agents.

Last updated on
Getting StartedAgent/Teams in config