{
  "schemaVersion": "1.0",
  "title": "Hermes Agent connector",
  "description": "Use the Hermes Agent connector when an AIP application needs typed access to one or more Hermes API servers. The connector exposes health, discovery, chat, responses, structured runs, sessions, jobs, and governed operator work through endpo",
  "canonical": "https://getaip.org/docs/connectors/hermes-agent",
  "route": "/docs/connectors/hermes-agent",
  "source": "docs/connectors/hermes-agent/README.md",
  "protocol": "Agent Interoperability Protocol",
  "protocolVersion": "1.0",
  "section": "Connectors",
  "documentType": "Connector",
  "language": "en",
  "revision": {
    "lastReviewedRevision": "d7cce13d1d555644d04a4d73c66c95b113737635",
    "documentationSourceRevision": "9192fef3695ad294994f2712f6d156241e5e92fb",
    "basis": "frontmatter"
  },
  "downloads": {
    "md": "/docs/download/connectors/hermes-agent.md",
    "txt": "/docs/download/connectors/hermes-agent.txt",
    "json": "/docs/download/connectors/hermes-agent.json",
    "pdf": "/docs/download/connectors/hermes-agent.pdf"
  },
  "content": {
    "format": "text/markdown",
    "markdown": "---\ntitle: Hermes Agent connector\ndescription: >-\n  Adopt Hermes Agent endpoints for governed chat, runs, sessions, jobs,\n  operator work, and AIP delegation\nkind: connector-overview\naudience: application-developer\nappliesTo: \"1.x\"\nwritingStandard: \"aip-docs/1.0\"\nlastReviewedRevision: \"d7cce13d1d555644d04a4d73c66c95b113737635\"\nconnector: hermes-agent\n---\n\n# Hermes Agent connector\n\nUse the Hermes Agent connector when an AIP application needs typed access to\none or more Hermes API servers. The connector exposes health, discovery, chat,\nresponses, structured runs, sessions, jobs, and governed operator work through\nendpoint-qualified AIP capabilities.\n\nThe connector runs in its own `aip-host-hermes-agent` process. Product-neutral\n`getaip-server` routes admitted actions to that host; it does not embed Hermes product\ncode, endpoint credentials, or model-provider credentials.\n\n## At a glance\n\n| Property | Reviewed value |\n|---|---|\n| Connector ID | `hermes-agent` |\n| Standalone process | `aip-host-hermes-agent` |\n| AIP workspace version | `2.0.0` |\n| Reviewed AIP source | `d7cce13d1d555644d04a4d73c66c95b113737635` |\n| Pinned Hermes source | `7426c09beee73bdff94d916015bac71384f6bc92` |\n| Connector profile | `aip.connector.hermes_agent.v1` |\n| Capability shape | `cap:hermes_agent:<endpoint_id>:<operation>` |\n| Capability count | 35 per endpoint |\n| Effective standalone endpoint limit | 14 under the fixed 512-capability host ceiling |\n| Provider authentication | Per-endpoint Bearer token for every operation except basic health |\n| Streaming | Chat, Responses API, run events, and session chat |\n| First-class delegation | Disabled by default; explicit policy and allowlists required |\n\nThe endpoint-file parser accepts between 1 and 1000 descriptors, but that is\nnot the deployable catalog limit. The common standalone host rejects a manifest\nabove 512 capabilities. At 35 capabilities per endpoint, 14 endpoints produce\n490 capabilities and 15 produce 525. The reviewed binary exposes no setting\nthat raises this ceiling.\n\nThese numbers describe source limits, not a scale qualification. Manifest byte\nsize, provider capacity, storage, model service, and deployment policy may\nrequire a smaller boundary.\n\n## Choose this connector when\n\nThe connector fits an integration that needs to:\n\n- discover models, skills, toolsets, and the Hermes API surface;\n- submit synchronous or streaming chat and Responses API work;\n- start, observe, approve, stop, and recover structured Hermes runs;\n- keep conversations in persisted Hermes sessions;\n- manage and trigger Hermes jobs through governed capabilities;\n- use Hermes as a long-running AIP operator with durable approval and\n  cancellation state;\n- route a first-class AIP delegation to a named Hermes endpoint under explicit\n  capability and scope allowlists.\n\nUse another integration boundary when the task needs an arbitrary Hermes URL\nor method, direct access to a model provider, an ungoverned autonomous agent,\nor endpoints owned by different AIP tenants in one standalone instance.\n\nDo not adopt the reviewed connector unchanged for a different Hermes revision.\nRe-audit the exact API-server routes and event shapes, then qualify the promoted\nconnector and provider artifacts together.\n\n## Understand the deployment boundary\n\nOne standalone connector instance owns one AIP tenant and one immutable\nmanifest containing 35 capabilities for each endpoint:\n\n1. An operator configures one or more named Hermes endpoints in an\n   owner-controlled JSON file.\n2. Every endpoint is bound to the standalone host's verified tenant. An\n   explicit different tenant causes startup to fail.\n3. The host builds 35 endpoint-qualified capabilities for each descriptor.\n4. Registry admission binds that exact manifest and artifact to the connector\n   instance and its replicas.\n5. An authenticated caller submits a native AIP action to `getaip-server`.\n6. The registry selects the tenant-owned Hermes instance and a healthy replica.\n7. The host validates the action and maps its endpoint and operation to one\n   fixed Hermes method and path.\n8. The per-endpoint credential is added inside the connector process, and the\n   result or stream returns through the native AIP lifecycle.\n\nAdding a descriptor changes the manifest and therefore requires a new admitted\nconnector version. Action input cannot select an unconfigured base URL, move an\nendpoint to another tenant, or supply a provider credential.\n\n## Choose a capability family\n\nEach configured endpoint receives the same five families.\n\n| Family | Count per endpoint | Supported outcome |\n|---|---:|---|\n| Health and discovery | 6 | Check health; list models, API capabilities, skills, and toolsets |\n| Chat and responses | 6 | Run synchronous or streaming chat and Responses API work; read or delete a stored response |\n| Structured runs and operator | 6 | Start, inspect, stream, approve, stop, or govern a durable operator run |\n| Sessions | 9 | List, create, read, update, delete, inspect messages, fork, or chat in a persisted session |\n| Jobs | 8 | List, create, read, update, delete, pause, resume, or run a durable job |\n| **Total** | **35** | Complete published surface for one endpoint |\n\nThe capability ID contains the normalized endpoint ID. Endpoint IDs are\nlowercase ASCII letters, digits, hyphens, or underscores after normalization.\nThey are stable routing identities, not display labels.\n\nFour operations are experimental in the reviewed manifest: skill discovery,\ntoolset discovery, stored-response lookup, and stored-response deletion. The\nother 31 are marked stable. Stability does not replace provider qualification.\n\n## Keep four execution roles separate\n\n| Role | What executes | Authority boundary |\n|---|---|---|\n| Direct Hermes capability | The connector calls one fixed Hermes API route | The native AIP action contract and endpoint binding are authoritative |\n| Hermes operator capability | A durable connector workflow starts or resumes a structured Hermes run | AIP approval, run binding, leases, and terminal provider state control settlement |\n| First-class AIP delegation | The runtime routes a child action to `agent:hermes_operator:<endpoint_id>` | Delegation policy, scope and capability allowlists, approval, and native child lifecycle are authoritative |\n| AIP MCP inside Hermes | Hermes uses deployment-configured MCP tools to call AIP | MCP authentication and tool allowlists are separate deployment responsibilities |\n\nThe Rust connector does not write Hermes MCP configuration. Enabling operator\ndelegation does not automatically give Hermes an AIP tool path, and configuring\nAIP MCP inside Hermes does not automatically authorize first-class delegation.\n\nFor a delegated action, the connector supplies the exact native child-action\ncontract to the stable `aip_call` tool. The result resolver then reads the\nnative durable AIP lifecycle. Hermes final prose is never accepted as the\nauthoritative business result.\n\n## Protect endpoint credentials and tenants\n\nBasic `GET /health` is the only operation that does not require endpoint\nauthentication. Every other published operation requires the endpoint's\nBearer token. The standalone binary reads an optional API-key file for each\ndescriptor; invoking a protected operation without a configured key fails\nbefore a useful provider result can be returned.\n\nSecret values are excluded from serialized endpoint configuration and debug\noutput. The default HTTP client:\n\n- accepts only configured `http` or `https` base URLs;\n- does not follow redirects, so it will not forward a Bearer token to a new\n  origin;\n- bounds connection and total request time;\n- maps provider and transport failures to typed connector errors.\n\nUse HTTPS and private service discovery outside a controlled loopback network.\nGive each tenant or trust domain independent Hermes and model-provider service\naccounts. Do not place endpoint keys, model credentials, or MCP tokens in AIP\naction input.\n\n## Apply operation safety by capability\n\nThe 35 operations do not share one retry or approval rule.\n\n- Read-only discovery, status, event, session-read, and job-read operations are\n  low risk.\n- Chat, response creation, run start, session changes, and most job changes are\n  medium risk because they can consume models or change provider state.\n- Operator execution, destructive deletes, and immediate job execution are\n  high risk.\n- Response deletion, run approval and stop, operator execution, session\n  deletion, and all state-changing job controls require AIP approval.\n- Destructive, transaction-declaring, and operator operations require an AIP\n  idempotency key.\n\nDo not interpret the AIP idempotency requirement as universal provider\nexactly-once behavior. The focused capability and operator pages define where\nthe connector can replay a stored result, where it can resume provider state,\nand where an uncertain outcome requires reconciliation.\n\n## Treat streams and cancellation explicitly\n\nThe connector maps bounded Hermes SSE to native AIP stream chunks. It rejects\noversized or malformed frames, limits the number of accepted events, and does\nnot infer success merely because a connection closed.\n\nDirect streaming operations end according to their operation-specific terminal\nevents. Runtime cancellation stops local stream processing. Structured operator\ncancellation is stronger: the connector durably records intent, sends the\nHermes stop request when a run ID is known, and polls for a terminal state.\nOnly provider-confirmed `cancelled` becomes an AIP cancelled result. A racing\ncompletion or failure remains authoritative; an unconfirmed stop becomes\noutcome unknown.\n\n## Govern operator and delegation work\n\nThe operator capability uses structured runs rather than stateless chat. A\ndurable profile-state record owns the start claim, run ID, stream progress,\npending approval, resume command, cancellation intent, and terminal result.\nThis prevents a restart from blindly starting the same Hermes run again.\n\nA failure after Hermes may have accepted a start but before the run ID is\nstored becomes outcome unknown and is not automatically replayed. Approval\nresume commands are generation-fenced so an old response cannot approve a\nlater prompt.\n\nFirst-class delegation is off by default. Enabling it requires explicit\ncapability and scope allowlists. Deployments that require delegated approval\nmust provide the runtime approval store; the standalone host also installs an\nauthoritative result resolver backed by native action and lifecycle stores.\n\nDo not expose recursive `aip_delegate` to the model-facing Hermes tool set. The\nexternal AIP orchestrator owns the delegation graph and its cycle, depth,\ntenant, approval, and child-action invariants.\n\n## Deliberate exclusions\n\nThe reviewed connector does not provide:\n\n- arbitrary HTTP forwarding or dynamic endpoint selection from action input;\n- a cross-tenant endpoint set in one standalone instance;\n- provider or model credentials inside protocol messages;\n- redirect following for authenticated provider requests;\n- default first-class delegation or unrestricted delegation policy;\n- authoritative delegated results from model prose;\n- connector-managed Hermes MCP profile writes;\n- native AIP transactions or inbound Hermes webhooks;\n- a guarantee that all 1000 syntactically accepted descriptors can be admitted;\n- current production readiness for an unqualified artifact or provider.\n\n## Evidence status\n\n| Evidence | What it supports | What it does not support |\n|---|---|---|\n| Source and 35-route matrix | Implemented endpoint-qualified contract at the reviewed commit | Execution of an unbuilt artifact |\n| Frozen conformance source | A deterministic 13-check gate, with transactions and inbound webhooks not applicable | A pass for the current artifact without a retained run |\n| Controlled fleet source | Registration and selected fixture-backed calls in the standalone topology | Real Hermes or model-provider compatibility |\n| Historical two-endpoint report | The exact older artifacts and seven recorded assertion groups | Current revision, rebuilt images, or another model route |\n\nRepeat deterministic, standalone-image, fleet, and isolated-live qualification\nfor the exact connector, Hermes, model-provider, MCP, and deployment identities\nbefore publishing a readiness claim.\n\n## Plan the next task\n\nContinue according to the task you need to complete:\n\n- configure one endpoint and prove a read-only call before enabling mutations;\n- bind endpoint credentials and every descriptor to the standalone host tenant;\n- select one of the five capability families and read its exact contract;\n- review the dedicated operator, delegation, cancellation, and MCP guidance\n  before enabling those higher-risk paths;\n- use the operations guidance for deployment, health, recovery, and rollout;\n- complete exact-artifact qualification before making a compatibility or\n  readiness claim.\n\nThe global references below own the shared fleet, MCP, and evidence rules.\n\n## Related documentation\n\n- [Connector documentation](../README.md)\n- [Pinned upstream baselines](../upstream-baselines.md)\n- [Connector fleet API](../../reference/connector-fleet-api.md)\n- [Use AIP through MCP](../../guides/use-aip-through-mcp.md)\n- [Historical Hermes Agent isolated-live evidence](../../testing/hermes-agent-isolated-live.md)\n",
    "text": "Hermes Agent connector\n\nUse the Hermes Agent connector when an AIP application needs typed access to\none or more Hermes API servers. The connector exposes health, discovery, chat,\nresponses, structured runs, sessions, jobs, and governed operator work through\nendpoint-qualified AIP capabilities.\n\nThe connector runs in its own aip-host-hermes-agent process. Product-neutral\ngetaip-server routes admitted actions to that host; it does not embed Hermes product\ncode, endpoint credentials, or model-provider credentials.\n\nAt a glance\n\n| Property | Reviewed value |\n\n| Connector ID | hermes-agent |\n| Standalone process | aip-host-hermes-agent |\n| AIP workspace version | 2.0.0 |\n| Reviewed AIP source | d7cce13d1d555644d04a4d73c66c95b113737635 |\n| Pinned Hermes source | 7426c09beee73bdff94d916015bac71384f6bc92 |\n| Connector profile | aip.connector.hermesagent.v1 |\n| Capability shape | cap:hermesagent:: |\n| Capability count | 35 per endpoint |\n| Effective standalone endpoint limit | 14 under the fixed 512-capability host ceiling |\n| Provider authentication | Per-endpoint Bearer token for every operation except basic health |\n| Streaming | Chat, Responses API, run events, and session chat |\n| First-class delegation | Disabled by default; explicit policy and allowlists required |\n\nThe endpoint-file parser accepts between 1 and 1000 descriptors, but that is\nnot the deployable catalog limit. The common standalone host rejects a manifest\nabove 512 capabilities. At 35 capabilities per endpoint, 14 endpoints produce\n490 capabilities and 15 produce 525. The reviewed binary exposes no setting\nthat raises this ceiling.\n\nThese numbers describe source limits, not a scale qualification. Manifest byte\nsize, provider capacity, storage, model service, and deployment policy may\nrequire a smaller boundary.\n\nChoose this connector when\n\nThe connector fits an integration that needs to:\n• discover models, skills, toolsets, and the Hermes API surface;\n• submit synchronous or streaming chat and Responses API work;\n• start, observe, approve, stop, and recover structured Hermes runs;\n• keep conversations in persisted Hermes sessions;\n• manage and trigger Hermes jobs through governed capabilities;\n• use Hermes as a long-running AIP operator with durable approval and\n  cancellation state;\n• route a first-class AIP delegation to a named Hermes endpoint under explicit\n  capability and scope allowlists.\n\nUse another integration boundary when the task needs an arbitrary Hermes URL\nor method, direct access to a model provider, an ungoverned autonomous agent,\nor endpoints owned by different AIP tenants in one standalone instance.\n\nDo not adopt the reviewed connector unchanged for a different Hermes revision.\nRe-audit the exact API-server routes and event shapes, then qualify the promoted\nconnector and provider artifacts together.\n\nUnderstand the deployment boundary\n\nOne standalone connector instance owns one AIP tenant and one immutable\nmanifest containing 35 capabilities for each endpoint:\n1. An operator configures one or more named Hermes endpoints in an\n   owner-controlled JSON file.\n2. Every endpoint is bound to the standalone host's verified tenant. An\n   explicit different tenant causes startup to fail.\n3. The host builds 35 endpoint-qualified capabilities for each descriptor.\n4. Registry admission binds that exact manifest and artifact to the connector\n   instance and its replicas.\n5. An authenticated caller submits a native AIP action to getaip-server.\n6. The registry selects the tenant-owned Hermes instance and a healthy replica.\n7. The host validates the action and maps its endpoint and operation to one\n   fixed Hermes method and path.\n8. The per-endpoint credential is added inside the connector process, and the\n   result or stream returns through the native AIP lifecycle.\n\nAdding a descriptor changes the manifest and therefore requires a new admitted\nconnector version. Action input cannot select an unconfigured base URL, move an\nendpoint to another tenant, or supply a provider credential.\n\nChoose a capability family\n\nEach configured endpoint receives the same five families.\n\n| Family | Count per endpoint | Supported outcome |\n\n| Health and discovery | 6 | Check health; list models, API capabilities, skills, and toolsets |\n| Chat and responses | 6 | Run synchronous or streaming chat and Responses API work; read or delete a stored response |\n| Structured runs and operator | 6 | Start, inspect, stream, approve, stop, or govern a durable operator run |\n| Sessions | 9 | List, create, read, update, delete, inspect messages, fork, or chat in a persisted session |\n| Jobs | 8 | List, create, read, update, delete, pause, resume, or run a durable job |\n| Total | 35 | Complete published surface for one endpoint |\n\nThe capability ID contains the normalized endpoint ID. Endpoint IDs are\nlowercase ASCII letters, digits, hyphens, or underscores after normalization.\nThey are stable routing identities, not display labels.\n\nFour operations are experimental in the reviewed manifest: skill discovery,\ntoolset discovery, stored-response lookup, and stored-response deletion. The\nother 31 are marked stable. Stability does not replace provider qualification.\n\nKeep four execution roles separate\n\n| Role | What executes | Authority boundary |\n\n| Direct Hermes capability | The connector calls one fixed Hermes API route | The native AIP action contract and endpoint binding are authoritative |\n| Hermes operator capability | A durable connector workflow starts or resumes a structured Hermes run | AIP approval, run binding, leases, and terminal provider state control settlement |\n| First-class AIP delegation | The runtime routes a child action to agent:hermesoperator: | Delegation policy, scope and capability allowlists, approval, and native child lifecycle are authoritative |\n| AIP MCP inside Hermes | Hermes uses deployment-configured MCP tools to call AIP | MCP authentication and tool allowlists are separate deployment responsibilities |\n\nThe Rust connector does not write Hermes MCP configuration. Enabling operator\ndelegation does not automatically give Hermes an AIP tool path, and configuring\nAIP MCP inside Hermes does not automatically authorize first-class delegation.\n\nFor a delegated action, the connector supplies the exact native child-action\ncontract to the stable aipcall tool. The result resolver then reads the\nnative durable AIP lifecycle. Hermes final prose is never accepted as the\nauthoritative business result.\n\nProtect endpoint credentials and tenants\n\nBasic GET /health is the only operation that does not require endpoint\nauthentication. Every other published operation requires the endpoint's\nBearer token. The standalone binary reads an optional API-key file for each\ndescriptor; invoking a protected operation without a configured key fails\nbefore a useful provider result can be returned.\n\nSecret values are excluded from serialized endpoint configuration and debug\noutput. The default HTTP client:\n• accepts only configured http or https base URLs;\n• does not follow redirects, so it will not forward a Bearer token to a new\n  origin;\n• bounds connection and total request time;\n• maps provider and transport failures to typed connector errors.\n\nUse HTTPS and private service discovery outside a controlled loopback network.\nGive each tenant or trust domain independent Hermes and model-provider service\naccounts. Do not place endpoint keys, model credentials, or MCP tokens in AIP\naction input.\n\nApply operation safety by capability\n\nThe 35 operations do not share one retry or approval rule.\n• Read-only discovery, status, event, session-read, and job-read operations are\n  low risk.\n• Chat, response creation, run start, session changes, and most job changes are\n  medium risk because they can consume models or change provider state.\n• Operator execution, destructive deletes, and immediate job execution are\n  high risk.\n• Response deletion, run approval and stop, operator execution, session\n  deletion, and all state-changing job controls require AIP approval.\n• Destructive, transaction-declaring, and operator operations require an AIP\n  idempotency key.\n\nDo not interpret the AIP idempotency requirement as universal provider\nexactly-once behavior. The focused capability and operator pages define where\nthe connector can replay a stored result, where it can resume provider state,\nand where an uncertain outcome requires reconciliation.\n\nTreat streams and cancellation explicitly\n\nThe connector maps bounded Hermes SSE to native AIP stream chunks. It rejects\noversized or malformed frames, limits the number of accepted events, and does\nnot infer success merely because a connection closed.\n\nDirect streaming operations end according to their operation-specific terminal\nevents. Runtime cancellation stops local stream processing. Structured operator\ncancellation is stronger: the connector durably records intent, sends the\nHermes stop request when a run ID is known, and polls for a terminal state.\nOnly provider-confirmed cancelled becomes an AIP cancelled result. A racing\ncompletion or failure remains authoritative; an unconfirmed stop becomes\noutcome unknown.\n\nGovern operator and delegation work\n\nThe operator capability uses structured runs rather than stateless chat. A\ndurable profile-state record owns the start claim, run ID, stream progress,\npending approval, resume command, cancellation intent, and terminal result.\nThis prevents a restart from blindly starting the same Hermes run again.\n\nA failure after Hermes may have accepted a start but before the run ID is\nstored becomes outcome unknown and is not automatically replayed. Approval\nresume commands are generation-fenced so an old response cannot approve a\nlater prompt.\n\nFirst-class delegation is off by default. Enabling it requires explicit\ncapability and scope allowlists. Deployments that require delegated approval\nmust provide the runtime approval store; the standalone host also installs an\nauthoritative result resolver backed by native action and lifecycle stores.\n\nDo not expose recursive aipdelegate to the model-facing Hermes tool set. The\nexternal AIP orchestrator owns the delegation graph and its cycle, depth,\ntenant, approval, and child-action invariants.\n\nDeliberate exclusions\n\nThe reviewed connector does not provide:\n• arbitrary HTTP forwarding or dynamic endpoint selection from action input;\n• a cross-tenant endpoint set in one standalone instance;\n• provider or model credentials inside protocol messages;\n• redirect following for authenticated provider requests;\n• default first-class delegation or unrestricted delegation policy;\n• authoritative delegated results from model prose;\n• connector-managed Hermes MCP profile writes;\n• native AIP transactions or inbound Hermes webhooks;\n• a guarantee that all 1000 syntactically accepted descriptors can be admitted;\n• current production readiness for an unqualified artifact or provider.\n\nEvidence status\n\n| Evidence | What it supports | What it does not support |\n\n| Source and 35-route matrix | Implemented endpoint-qualified contract at the reviewed commit | Execution of an unbuilt artifact |\n| Frozen conformance source | A deterministic 13-check gate, with transactions and inbound webhooks not applicable | A pass for the current artifact without a retained run |\n| Controlled fleet source | Registration and selected fixture-backed calls in the standalone topology | Real Hermes or model-provider compatibility |\n| Historical two-endpoint report | The exact older artifacts and seven recorded assertion groups | Current revision, rebuilt images, or another model route |\n\nRepeat deterministic, standalone-image, fleet, and isolated-live qualification\nfor the exact connector, Hermes, model-provider, MCP, and deployment identities\nbefore publishing a readiness claim.\n\nPlan the next task\n\nContinue according to the task you need to complete:\n• configure one endpoint and prove a read-only call before enabling mutations;\n• bind endpoint credentials and every descriptor to the standalone host tenant;\n• select one of the five capability families and read its exact contract;\n• review the dedicated operator, delegation, cancellation, and MCP guidance\n  before enabling those higher-risk paths;\n• use the operations guidance for deployment, health, recovery, and rollout;\n• complete exact-artifact qualification before making a compatibility or\n  readiness claim.\n\nThe global references below own the shared fleet, MCP, and evidence rules.\n\nRelated documentation\n• Connector documentation (../README.md)\n• Pinned upstream baselines (../upstream-baselines.md)\n• Connector fleet API (../../reference/connector-fleet-api.md)\n• Use AIP through MCP (../../guides/use-aip-through-mcp.md)\n• Historical Hermes Agent isolated-live evidence (../../testing/hermes-agent-isolated-live.md)\n"
  },
  "integrity": {
    "algorithm": "sha256",
    "sourceDigest": "6d0b108688211c74adfdfe9a188e9e0585a6cdd94b11847c372b90aafce4aea8"
  }
}