# 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.

## Enrich Agent With Schema

 - [POST /forge-agents/api/v1/agents/{agent_id}/enrich-schema](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/enrich_agent_with_schema_api_v1_agents__agent_id__enrich_schema_post.md): Trigger output_json_schema enrichment for an existing agent.

This endpoint enriches the agent's tasks with auto-generated output_json_schema
and updates the agent configuration in the database.

Features:
- Fetches the latest agent configuration from database
- Generates output_json_schema for tasks that need them (typically 5-15 seconds per task)
- Updates the agent in database with enriched schemas
- Can run synchronously (blocks until complete) or as a background task

Query Parameters:
- background: If true, runs enrichment as background task and returns immediately.
             If false (default), runs synchronously and returns enriched schemas.

Use Cases:
- Re-generate schemas after agent updates
- Generate schemas for agents created without them
- Refresh schemas when requirements change

Returns:
- If background=false: Returns object with schemas, agent_id, and total count
                      Example: {
                          "schemas": {"task_name": {...json_schema...}, ...},
                          "agent_id": "...",
                          "total_schemas": 2
                      }
- If background=true: Returns status message with agent_id

## Get Agent Feedback

 - [GET /forge-agents/api/v1/agents/feedback](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_feedback_api_v1_agents_feedback_get.md): Get agent feedback with optional filters.

This endpoint retrieves feedback records with support for multiple filters
and pagination. All filters are optional and can be combined.

Query Parameters:
- agent_id: Filter by agent configuration (ca_configuration_id)
- user_id: Filter by feedback provider
- from_date: Start timestamp for filtering by creation date
- to_date: End timestamp for filtering by creation date
- upvote: Filter by upvote status (true for positive, false for negative)
- execution_id: Filter by specific execution
- session_id: Filter by session
- limit: Number of items per page (default: 10, max: 100)
- offset: Number of items to skip for pagination (default: 0)

Example:

GET /agents/feedback?agent_id=agent_conf_001&upvote=false&from_date=2026-01-01


Returns:
- 200 OK with paginated list of feedback records and total count

## Create Agent Feedback

 - [POST /forge-agents/api/v1/agents/feedback](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/create_agent_feedback_api_v1_agents_feedback_post.md): Create feedback for an agent response.

This endpoint allows users to provide feedback (upvote/downvote with optional comments)
on agent responses. The collected feedback will be stored and can be used to improve
future agent executions.

Features:
- Capture user feedback (thumbs up/down and comments) on agent responses
- Store feedback linked to specific executions and sessions
- Support cross-session and cross-user feedback analysis

Request Body:
- user_message: The user's input/query
- agent_message: The agent's response being rated
- upvote: True for thumbs up, False for thumbs down
- feedback_text: Optional text feedback/comment
- execution_id: ID of the agent execution
- session_id: Session identifier
- ca_configuration_id: Agent configuration ID

Note: tenant_id, feedback_by, and insert_by are automatically set from the authenticated user context.

Returns:
- 201 Created with feedback record including generated feedback_id

## Get Agent Feedback By Id

 - [GET /forge-agents/api/v1/agents/feedback/{feedback_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_feedback_by_id_api_v1_agents_feedback__feedback_id__get.md): Get a single agent feedback record by ID.

This endpoint retrieves a specific feedback record using its unique ID.

Path Parameters:
- feedback_id: The ID of the feedback record to retrieve

Returns:
- 200 OK with the feedback record
- 404 Not Found if feedback_id doesn't exist

Example:

GET /agents/feedback/550e8400-e29b-41d4-a716-446655440000

## Update Agent Feedback

 - [PUT /forge-agents/api/v1/agents/feedback/{feedback_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/update_agent_feedback_api_v1_agents_feedback__feedback_id__put.md): Update existing agent feedback.

This endpoint allows users to modify their previously submitted feedback.
Users can change the upvote/downvote status or update the feedback text.

Path Parameters:
- feedback_id: The ID of the feedback record to update

Request Body:
- upvote: Optional - True for thumbs up, False for thumbs down
- feedback_text: Optional - Updated text feedback/comment

Note: update_by is automatically set from the authenticated user context.

Returns:
- 200 OK with updated feedback record
- 404 Not Found if feedback_id doesn't exist

## Delete Agent Feedback

 - [DELETE /forge-agents/api/v1/agents/feedback/{feedback_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/delete_agent_feedback_api_v1_agents_feedback__feedback_id__delete.md): Delete agent feedback.

This endpoint permanently deletes a feedback record. This operation cannot be undone.

Path Parameters:
- feedback_id: The ID of the feedback record to delete

Returns:
- 204 No Content on successful deletion
- 404 Not Found if feedback_id doesn't exist

## Refresh Agent Feedback Summary

 - [POST /forge-agents/api/v1/agents/feedback/summarize/{agent_id}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/refresh_agent_feedback_summary_api_v1_agents_feedback_summarize__agent_id__post.md): Refresh (create or update) the feedback summary for an agent.

Triggers an on-demand re-ranking of all feedback records for the given
agent and regenerates the aggregated summary stored in
xf_agent_feedback_summary. Unlike the automatic background summarization
that runs after each feedback create/update/delete, this endpoint runs
synchronously and returns the resulting summary so the caller can confirm
the outcome.

Path Parameters:
- agent_id: The agent configuration ID (ca_configuration_id)

Returns:
- 200 OK with the refreshed summary record
- 404 Not Found if no summary could be generated (e.g. no feedback exists)

## 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.

## Search Agents By Capabilities

 - [GET /forge-agents/api/v1/agents/search/by-capabilities](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/search_agents_by_capabilities_api_v1_agents_search_by_capabilities_get.md): Search agents by capability tags.

This endpoint allows you to find agents based on their capability tags. You can search for agents
that have ANY of the specified tags (match_all=false) or ALL of the specified tags (match_all=true).

Example: GET /api/v1/agents/search/by-capabilities?tags=python&tags=data_analysis&match_all=false

## Get All Capability Tags

 - [GET /forge-agents/api/v1/agents/capabilities/tags](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_all_capability_tags_api_v1_agents_capabilities_tags_get.md): Get all unique capability tags across all active agents for the current tenant.

Returns a sorted list of all unique capability tags that have been assigned to agents.
Useful for tag autocomplete and discovery features.

Example: GET /api/v1/agents/capabilities/tags
Returns: ["data_analysis", "python", "visualization", "web_research"]

## List Agent Versions

 - [GET /forge-agents/api/v1/agents/{agent_id}/versions](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/list_agent_versions_api_v1_agents__agent_id__versions_get.md): List version history for an agent configuration.

## Get Agent Version

 - [GET /forge-agents/api/v1/agents/{agent_id}/versions/{version}](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/get_agent_version_api_v1_agents__agent_id__versions__version__get.md): Get a specific version of an agent configuration.

## Rollback Agent Version

 - [POST /forge-agents/api/v1/agents/{agent_id}/versions/{version}/rollback](https://docs.businessai.uniphorecloud.com/api-reference/api/agents/rollback_agent_version_api_v1_agents__agent_id__versions__version__rollback_post.md): Rollback an agent configuration to a previous version.

## 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): Execute an agent. The agent execution runs in a dedicated thread pool
to prevent blocking the main event loop and ensure health probes remain responsive.

## 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)