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 approved live data or actions from the
   host application. 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 Self-service business capabilities.
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, activation, 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,
contract-test, activate, and verify through chat. 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 activation and final chat verification
pass. Never request Admin API access or internal secrets.

Expected result

A successful run leaves a tested first HTTP message and a documented choice of

HTTP or capabilities. Capability work is complete only after the target

revision is active and a chat response is verified against the approved 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