Source: docs/integration/use-with-an-agent.md

Use Forgium Agent with an agent

This is the single public entrypoint for a coding agent integrating a host

application with Forgium Agent. The public documentation is the canonical

contract. The optional Skill is not currently distributed as an installable

package; use this protocol unless your runtime already supports a verified

local SKILL.md.

Machine-readable discovery

An agent can discover the complete public contract without guessing URLs:

• Agent manifest — canonical resources, versions,
  routes, required environment variables, and stop conditions.
• Agent index — generated resource index and hashes.
• LLM index — concise reading order and route summary.
• Raw OpenAPI contract — exact public request and response
  schemas.
• Contract retrieval — direct download, validation, and
  blocker reporting when an agent cannot locate the contract.
• HTTP integration reference — server-side
  adapter pattern and production checklist.

The same resources are available from the public site at:

https://docs.forgium.dev/agent-manifest.json
https://docs.forgium.dev/agent-index.json
https://docs.forgium.dev/llms.txt
https://docs.forgium.dev/docs/integration/api.openapi.yaml

Use only links published by the manifest or this page. Do not guess or

enumerate undocumented openapi.json, swagger.json, or API paths.

Decision protocol

1. Read the agent manifest, this page, the
   Overview, and Environments.
2. Determine the goal:
   - Connectivity test only: do not inspect or modify an unrelated
   repository; use Getting started to send the first
   HTTP message.
   - Code integration: identify the host application's repository and where
   the integration belongs. Before running repository commands, confirm the
   working directory with pwd and change to the host repository explicitly.
   Do not assume a data source, tunnel, framework, or deployment model.
3. For a code integration, choose the smallest applicable route:
   - HTTP: the host application needs a synchronous agent response.
   - Capabilities: the agent needs live data or a host-owned operation
   preparation result. Capabilities may coexist with HTTP, but are not
   required for a basic message integration.
4. When a real API call is needed, confirm the target environment's
   FORGIUM_AGENT_BASE_URL and FORGIUM_AGENT_API_KEY. If either is missing,
   request access; continue only with local work or mocks,
   and do not claim an end-to-end result.
5. Read the OpenAPI contract and, if discovery fails,
   follow Contract retrieval before writing calls.
   For an HTTP code integration, use the HTTP integration reference
   as a pattern only; implement only what the repository needs.
6. Run the applicable local or authenticated smoke test. For a code integration,
   also run the host repository's tests. For capabilities, follow the complete
   lifecycle in Capability quickstart or the
   detailed Self-service business capabilities reference.
7. Report what changed, the evidence that passed, and every concrete blocker
   with its next action. Do not collapse multiple blockers into an artificial
   single blocker.

Stop conditions

Stop the integration and report the blocker instead of guessing or probing when:

• the canonical OpenAPI contract or selected route guide cannot be reached
  through the published links; use Contract retrieval
  once, then report the exact HTTP status and content type instead of probing;
• FORGIUM_AGENT_BASE_URL or FORGIUM_AGENT_API_KEY is missing for a real API
  call;
• the access bundle does not identify the requested environment;
• the endpoint URL, credential, or capability manifest is a placeholder,
  unauthenticated, or belongs to another environment; or
• a contract test, explicit enable/disable transition, or final chat
  verification fails.

A missing Git repository is not by itself an integration failure. Only run Git

commands when the host repository uses Git or when version-control evidence was

specifically requested.

Route reference

Copy this prompt

You are integrating my application with Forgium Agent. Use only the official
public integration documentation at https://docs.forgium.dev/docs.

Start with these canonical resources; do not guess or enumerate undocumented
URLs:
1. https://docs.forgium.dev/agent-manifest.json
2. https://docs.forgium.dev/docs/integration/use-with-an-agent
3. https://docs.forgium.dev/docs/integration/overview
4. https://docs.forgium.dev/docs/integration/environments
5. https://docs.forgium.dev/docs/integration/api.openapi.yaml

Use the manifest's published links for the selected route:
- HTTP quickstart: https://docs.forgium.dev/docs/integration/getting-started
- Capabilities lifecycle: https://docs.forgium.dev/docs/integration/capability-handoff
- Request access: https://docs.forgium.dev/docs/integration/request-access
- Contract retrieval: https://docs.forgium.dev/docs/integration/contract-retrieval
- HTTP integration reference: https://docs.forgium.dev/docs/integration/reference-implementation

If you are only testing connectivity, do not inspect or modify an unrelated
repository: use the access bundle and the HTTP quickstart to send one message.
Do not run repository or git discovery commands for a connectivity-only test.

If you are implementing code, first confirm the working directory with `pwd`
and explicitly inspect the host application's repository. Choose the minimum
integration it actually needs:
- HTTP when it needs a synchronous agent response; or
- capabilities when the agent needs approved live data or actions from the host.
Capabilities are optional and may coexist with HTTP.

When a real API call or deployment is required, confirm these values for the
selected environment before using them:
- FORGIUM_AGENT_BASE_URL
- FORGIUM_AGENT_API_KEY
If either is missing, ask the Forgium administrator for the environment-specific
access bundle and continue only with local implementation or mocks.

Read the canonical OpenAPI contract before generating requests. If the agent
cannot locate it through the published links, follow the Contract retrieval
commands once and report the exact result. Do not substitute another contract.
Implement only the applicable route, run tests, and record evidence. For capabilities, use the
public lifecycle: protect and expose the host endpoint, provision its scoped
credential through the Public API vault, create a secret-free manifest, import
to publish an active revision, contract-test, and verify through chat. Use
explicit `enable` or `disable` transitions with the current `If-Match` revision.
Repeat separately per
environment. Never use a placeholder URL or an unauthenticated endpoint.

If a published page or the canonical contract is unavailable, stop and report
that blocker. Do not probe guessed OpenAPI, Swagger, API, or internal URLs.
Report every blocker separately with its next action.

Report changes, verification evidence, and every actionable blocker. Do not
claim a capability is active unless import validation and final chat
verification pass. Never request Admin API access or internal secrets.

Current runtime behavior

The following constraints apply to the current version of Forgium Agent:

• One capability per turn. The agent executes at most one capability call per turn. A second operation requires another turn or one capability designed for the complete intent.
• Clarification over fabrication. When a required argument is missing, the agent asks for clarification rather than inventing values.
• Safe history reuse. The agent reuses unambiguous context from conversation history but asks for confirmation when the history is ambiguous.
• Validated result context. After a successful capability returns one unique, bounded name-like reference, Forgium may reuse it for a clearly related follow-up in the same conversation. Explicit conflicting context is not carried forward; IDs, credentials, amounts, dates, and raw results are not stored as conversational references, and the executor revalidates every argument.
• No internal ID exposure. The agent does not expose internal identifiers (database IDs, revision numbers) unless the capability explicitly returns them.
• Grounded responses. The agent bases its responses on the capability result and must not invent data when the result is empty or the capability fails.
• Host-owned operations. Contract 5 capabilities are read-only. A host may expose a result_handling: "host_interaction" preparation capability; Forgium returns a bounded interaction union and never executes or authorizes the operation.
• Just-in-time host preflight. Forgium invokes the preparation capability after the user expresses an operation intent. The host resolves matching resources and checks current eligibility then; it does not need to predict the intent in advance. not_found covers both no match and matching-but-ineligible resources.
• Opaque references. Route by interaction.owner and interaction.type. Keep operation_ref, selection_ref, and option_ref in the host flow; they are not sent to Workers AI, written to conversation history or metadata, persisted by Forgium, or resent in a later interaction.
• Revalidate before mutation. Preparation is not a lock or authorization grant. After confirmation, the host must recheck authorization, state, concurrency/revision, and idempotency before mutating.
• Terminal reporting. The host performs selection, confirmation, authorization, concurrency, idempotency, and mutation. It may report only the terminal status through POST /v1/conversations/{conversationId}/operation-results.

For detailed behavior examples, see Self-service business capabilities.

Expected result

A successful run leaves a tested first HTTP message and, when needed, a

read-only capability or host-interaction preparation capability active and

verified against the host endpoint.

Continue with:

• Overview
• Getting started for the manual HTTP quickstart
• Environments
• Request access
• Contract retrieval
• HTTP integration reference
• Self-service business capabilities
• Public API contract