Toolhouse Agent Management

naftiko: "1.0.0-alpha1"

info:
  label: "Toolhouse Agent Management"
  description: "Workflow capability for managing the full AI agent lifecycle on Toolhouse — from agent creation and tool configuration to execution monitoring, Agent Studio sessions, and scheduled runs."
  tags:
    - AI Agents
    - Agent Infrastructure
    - Backend As A Service
    - MCP
    - Tools
    - Toolhouse
  created: "2026-05-03"
  modified: "2026-05-03"

binds:
  - namespace: env
    keys:
      TOOLHOUSE_API_KEY: TOOLHOUSE_API_KEY

capability:
  consumes:
    - import: toolhouse-platform
      location: ./shared/toolhouse-platform.yaml

  exposes:
    - type: rest
      port: 8080
      namespace: toolhouse-agent-management-api
      description: "Unified REST API for the full Toolhouse agent lifecycle management workflow."
      resources:
        - path: /v1/agents
          name: agents
          description: "Manage AI agents."
          operations:
            - method: GET
              name: list-agents
              description: "List all agents for the authenticated user."
              call: "toolhouse-platform.list-agents"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-agent
              description: "Create or update an AI agent."
              call: "toolhouse-platform.upsert-agent"
              with:
                name: "rest.name"
                description: "rest.description"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/agents/{agent_id}
          name: agent
          description: "Get a specific agent."
          operations:
            - method: GET
              name: get-agent
              description: "Get details of a specific agent."
              call: "toolhouse-platform.get-agent"
              with:
                agent_id: "rest.agent_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/agent-runs
          name: agent-runs
          description: "Agent execution history."
          operations:
            - method: GET
              name: list-agent-runs
              description: "List all agent execution runs."
              call: "toolhouse-platform.list-agent-runs"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/agent-runs/{run_id}
          name: agent-run
          description: "Get a specific agent run."
          operations:
            - method: GET
              name: get-agent-run
              description: "Get details and status of a specific agent run."
              call: "toolhouse-platform.get-agent-run"
              with:
                run_id: "rest.run_id"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/tools
          name: tools
          description: "Available tools in the Toolhouse library."
          operations:
            - method: GET
              name: list-tools
              description: "List all available tools."
              call: "toolhouse-platform.list-tools"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/bundles
          name: bundles
          description: "Tool bundles for grouping tools."
          operations:
            - method: GET
              name: list-bundles
              description: "List all tool bundles."
              call: "toolhouse-platform.list-bundles"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-bundle
              description: "Create a new tool bundle."
              call: "toolhouse-platform.create-bundle"
              with:
                name: "rest.name"
                tools: "rest.tools"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/studio-chats
          name: studio-chats
          description: "Agent Studio chat sessions."
          operations:
            - method: GET
              name: list-studio-chats
              description: "List all Agent Studio chat sessions."
              call: "toolhouse-platform.list-studio-chats"
              outputParameters:
                - type: object
                  mapping: "$."
            - method: POST
              name: create-studio-chat
              description: "Start a new Agent Studio chat session."
              call: "toolhouse-platform.create-studio-chat"
              with:
                agentId: "rest.agentId"
              outputParameters:
                - type: object
                  mapping: "$."

        - path: /v1/api-keys
          name: api-keys
          description: "API key management."
          operations:
            - method: GET
              name: list-api-keys
              description: "List all API keys for the authenticated user."
              call: "toolhouse-platform.list-api-keys"
              outputParameters:
                - type: object
                  mapping: "$."

    - type: mcp
      port: 9090
      namespace: toolhouse-agent-management-mcp
      transport: http
      description: "MCP server for AI-assisted Toolhouse agent lifecycle management."
      tools:
        - name: list-agents
          description: "List all Toolhouse AI agents for the authenticated user."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.list-agents"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-agent
          description: "Get the full configuration and details of a specific Toolhouse agent."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.get-agent"
          with:
            agent_id: "tools.agent_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-agent
          description: "Create or update a Toolhouse AI agent definition with tools, bundles, and system prompt."
          hints:
            readOnly: false
            idempotent: false
          call: "toolhouse-platform.upsert-agent"
          with:
            name: "tools.name"
            description: "tools.description"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-agent-runs
          description: "List historical execution runs for Toolhouse agents with pagination."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.list-agent-runs"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-agent-run
          description: "Get the details, status, and results of a specific Toolhouse agent run."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.get-agent-run"
          with:
            run_id: "tools.run_id"
          outputParameters:
            - type: object
              mapping: "$."
        - name: get-agent-run-logs
          description: "Retrieve the execution logs for a specific Toolhouse agent run."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.get-agent-run-logs"
          with:
            run_id: "tools.run_id"
          outputParameters:
            - type: array
              mapping: "$."
        - name: list-tools
          description: "List all available tools in the Toolhouse tool library."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.list-tools"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-bundles
          description: "List all tool bundles configured for the authenticated user."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.list-bundles"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-bundle
          description: "Create a new tool bundle grouping specific tools together."
          hints:
            readOnly: false
            idempotent: false
          call: "toolhouse-platform.create-bundle"
          with:
            name: "tools.name"
            tools: "tools.tools"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-studio-chats
          description: "List all Agent Studio chat sessions for visual agent development."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.list-studio-chats"
          outputParameters:
            - type: object
              mapping: "$."
        - name: create-studio-chat
          description: "Create a new Agent Studio chat session for interactive agent development."
          hints:
            readOnly: false
            idempotent: false
          call: "toolhouse-platform.create-studio-chat"
          with:
            agentId: "tools.agentId"
          outputParameters:
            - type: object
              mapping: "$."
        - name: list-api-keys
          description: "List all API keys for the authenticated Toolhouse user."
          hints:
            readOnly: true
            idempotent: true
          call: "toolhouse-platform.list-api-keys"
          outputParameters:
            - type: object
              mapping: "$."
        - name: subscribe-to-agent
          description: "Subscribe to a paid Toolhouse agent to enable access."
          hints:
            readOnly: false
            idempotent: false
          call: "toolhouse-platform.subscribe-to-agent"
          with:
            agent_id: "tools.agent_id"
          outputParameters:
            - type: object
              mapping: "$."