# Agents

APIs for Agents.

## List All Agent Groups

 - [GET /forge-agents/api/v1/agents/by-all-groups](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/list_all_agent_groups_api_v1_agents_by_all_groups_get.md): Admin-only: return all groups and their agent mappings.

## Get Agent Groups

 - [GET /forge-agents/api/v1/agents/{agent_id}/groups](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_groups_api_v1_agents__agent_id__groups_get.md): Get all groups assigned to an agent.

## Assign Agent Groups

 - [POST /forge-agents/api/v1/agents/{agent_id}/groups](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/assign_agent_groups_api_v1_agents__agent_id__groups_post.md): Assign (and sync) groups to an agent.
If some existing groups are not included in the request, they are removed.
Admin-only endpoint.

## Check Agent Access

 - [GET /forge-agents/api/v1/agents/{agent_id}/access](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/check_agent_access_api_v1_agents__agent_id__access_get.md): Check if the current user has access to the specified agent.

## List Agents By Groups

 - [GET /forge-agents/api/v1/agents/by-groups](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/list_agents_by_groups_api_v1_agents_by_groups_get.md): Return agents grouped by user groups.

## List All Agent Models

 - [GET /forge-agents/api/v1/models](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/list_all_agent_models_api_v1_models_get.md): return all models.

## Get All Agents

 - [GET /forge-agents/api/v1/agents](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_all_agents_api_v1_agents_get.md)

## Create Crewai Agents

 - [POST /forge-agents/api/v1/agents](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/create_crewai_agents_api_v1_agents_post.md)

## Delete All Agents

 - [DELETE /forge-agents/api/v1/agents](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/delete_all_agents_api_v1_agents_delete.md)

## Get Available Planning Models

 - [GET /forge-agents/api/v1/agents/planning-models](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_available_planning_models_api_v1_agents_planning_models_get.md): Get list of available planning models for agent task planning.

Returns a list of supported planning models with metadata including:
- id: Model identifier used internally and stored in agent configuration
- display_name: Human-readable name for UI display
- description: Details about the model's capabilities
- provider: Model provider (e.g., Fireworks AI, OpenAI)
- recommended: Whether this model is recommended
- recommendation_reason: Why this model is recommended (if applicable)

The 'id' field should be used when creating/updating agents with a planning_model.

## Get Agents

 - [GET /forge-agents/api/v1/agents/{agent_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agents_api_v1_agents__agent_id__get.md)

## Update Agents

 - [PUT /forge-agents/api/v1/agents/{agent_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/update_agents_api_v1_agents__agent_id__put.md)

## Delete Agents

 - [DELETE /forge-agents/api/v1/agents/{agent_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/delete_agents_api_v1_agents__agent_id__delete.md): Delete an agent by ID.

Validates that the agent is not currently linked as a sub-agent to any supervisor agents
before deletion. If linked, returns 409 Conflict with details of supervisor agents.

Response on success (200 OK):
    {
        "agent_id": "...",
        "message": "...",  # For debugging/logging only - do NOT display to end users
        "sub_agents": [...]  # Only included if deleting a supervisor with sub-agents
    }

Response on conflict (409):
    {
        "error_code": 409,
        "error_message": "...",
        "data": {
            "agent_id": "...",
            "agent_name": "...",
            "linked_supervisors": [{"name": "...", "agent_id": "..."}]
        }
    }

IMPORTANT: The 'message' field in success responses is provided for debugging and
troubleshooting purposes only. Clients SHOULD NOT display these messages directly
to end users. Instead, implement i18n-compliant messaging on the frontend based on
the response data (agent_id, sub_agents, etc.).

## Update Agent Published Status

 - [PATCH /forge-agents/api/v1/agents/{agent_id}/published-status](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/update_agent_published_status_api_v1_agents__agent_id__published_status_patch.md)

## Generate Agent Output Schema

 - [POST /forge-agents/api/v1/agents/schema](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/generate_agent_output_schema_api_v1_agents_schema_post.md): Synchronously generate output_json_schema for agent tasks.

This endpoint requires an id and optionally accepts an agent_config.
- If agent_config is provided: uses it directly (does not fetch from DB)
- If agent_config is not provided: fetches the agent from DB using id

Returns the agent configuration with output_json_schema fields populated for tasks that need them.
This is a synchronous operation that may take 5-15 seconds per task.

Request Body Examples:
json
// Case 1: Fetch agent from DB using id
{
    "id": "123e4567-e89b-12d3-a456-426614174000"
}

// Case 2: Use provided agent_config directly
{
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_config": {
        "name": "Research Agent",
        "role": "Researcher",
        "goal": "Find information",
        "tasks": [...]
    }
}


Schema Generation Details:
- Uses LLM (gpt-4.1-mini) to analyze agent metadata and generate Pydantic models
- Inputs to LLM: agent name, role, goal, backstory, task name, description, expected_output
- Generates 5-12 field JSON schemas tailored to the agent's purpose
- Converts Pydantic models to JSON Schema Draft 7 format

Generation Conditions:
- Only generates if output_json_schema does NOT already exist
- Only generates if output_format is "json", "markdown", or None
- Skips tasks with output_format like "text" or other non-json formats
- Never overwrites existing schemas

NOTE: This does NOT save the agent to the database - it only returns the enriched config.

## Get Agent Supervisors

 - [GET /forge-agents/api/v1/agents/{agent_id}/supervisors](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_supervisors_api_v1_agents__agent_id__supervisors_get.md): Get all supervisor agents that have the specified agent as a sub-agent.

Returns a list of supervisors with their names and IDs that are currently
using the specified agent as a sub-agent.

## Agent Execution

 - [POST /forge-agents/api/v1/agents/execute](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/agent_execution_api_v1_agents_execute_post.md)

## Agent Execution Sse

 - [POST /forge-agents/api/v1/agents/execute/stream](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/agent_execution_sse_api_v1_agents_execute_stream_post.md): Execute agents with Server-Sent Events (SSE) streaming.
Unidirectional communication: client sends one query, server streams response.

Features:
- SSE streaming for real-time updates
- Session management for conversation context
- Memory support for maintaining context
- Sequential or parallel tool execution
- Custom agent inputs

## Generate Agents

 - [POST /forge-agents/api/v1/agents/generate](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/generate_agents_api_v1_agents_generate_post.md)

## Prompt Suggestions

 - [GET /forge-agents/api/v1/agents/{agent_id}/prompt-suggestions](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/prompt_suggestions_api_v1_agents__agent_id__prompt_suggestions_get.md)

## Get Agent Runs

 - [GET /forge-agents/api/v1/agent-runs](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_runs_api_v1_agent_runs_get.md)

## Get Agent Output Schema

 - [GET /forge-agents/api/v1/agents/{agent_id}/output-schema](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_output_schema_api_v1_agents__agent_id__output_schema_get.md)

## Get Agent Execution Trace

 - [GET /forge-agents/api/v1/agents/traces/{execution_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_execution_trace_api_v1_agents_traces__execution_id__get.md)

## Reset Agent Session

 - [DELETE /forge-agents/api/v1/agents/sessions/{session_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/reset_agent_session_api_v1_agents_sessions__session_id__delete.md): Reset (delete) an agent conversation session.

This endpoint deletes all checkpoints, conversation history, and pending writes
associated with a specific session ID. Use this to:
- Clear conversation history for a user
- Reset context when starting a new conversation
- Clean up after testing/debugging
- Implement "clear chat" functionality

Note: This operation is irreversible. Once deleted, the conversation history
cannot be recovered.

Args:
    session_id: The session ID (thread_id) to reset. This is the same session_id
               used in the /agents/execute WebSocket endpoint.

Returns:
    dict: Deletion summary with message and session_id

## Get Agent Runs (Paginated)

 - [GET /forge-agents/api/v2/agent-runs](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_runs__paginated__api_v2_agent_runs_get.md)