Skip to content

Agent Engine

The agent engine hosts multi-step orchestration workflows and tool logic.

Responsibilities

  • Agent planning/execution flows
  • Tool invocation orchestration
  • Coordinating LLM, RAG, and data-access integrations
  • Keeping business workflow logic out of Flask route handlers

API Surface

  • GET /health
  • POST /v1/agent-executions
  • GET /v1/agent-executions/{id}

Execution records are persisted to PostgreSQL when DATABASE_URL is available; otherwise an in-memory fallback store is used.

Backend resolves the active platform bindings and passes them to agent engine as an execution-scoped platform_runtime snapshot. Prompt- and message-based executions perform a real LLM call through the active llm_inference provider. Explicit input.retrieval requests use the canonical retrieval contract, and agent engine executes semantic / keyword / hybrid retrieval against the active runtime bindings before the LLM call.

Canonical retrieval semantics, normalized result fields, and backend/engine ownership boundaries are documented in Retrieval Contract.

Tool/runtime convergence now adds two optional runtime capabilities to that same snapshot:

  • mcp_runtime for MCP-backed remote/general-purpose tools
  • sandbox_execution for native Python execution tools

Execution flow summary:

  1. Normalize execution input into ConversationState and optional RetrievalRequest.
  2. Resolve the agent spec and enforce execute permissions.
  3. Validate runtime dependencies and resolve allowed tools.
  4. Execute semantic / keyword / hybrid retrieval against the active embeddings and vector_store bindings when requested.
  5. Call the active llm_inference provider with normalized messages and tool definitions.
  6. Dispatch tool calls through the active mcp_runtime or sandbox_execution provider.
  7. Assemble ExecutionResult and persist execution state transitions.

The code is now split into explicit seams:

  • agent_engine/app/execution_pipeline for DTOs and stage orchestration
  • agent_engine/app/retrieval for retrieval normalization and execution
  • agent_engine/app/tool_runtime for transport-specific tool dispatch
  • agent_engine/app/policies for policy and agent-resolution stages

The canonical HTTP entrypoint now resolves directly through execution_pipeline.runner; services/execution_service.py is kept only as a lightweight compatibility shim while older imports are phased out.

These seams are intended to support future Vanessa-specific planner, memory/retrieval, response policy, and tool strategy modules without branching the generic execution flow.

Current canonical built-in tools:

  • tool.web_search via transport: mcp; the gateway resolves it through local SearXNG, so it requires online runtime
  • tool.python_exec via transport: sandbox_http

Successful execution results now populate normalized tool_calls metadata alongside model_calls, embedding_calls, and canonical retrieval_calls.

Canonical service notes: agent_engine/README.md.

Owner: Agent engine maintainers. Update cadence: whenever orchestration patterns, tool contracts, or workflow behavior changes.