Source: docs/integration/getting-started.md

Getting started

This path uses the HTTP channel to verify that your application can send a text

message and receive a synchronous agent response.

1. Receive the access bundle

Request the access bundle from the Forgium administrator

for the target environment. It contains:

FORGIUM_AGENT_BASE_URL=https://<public-api-host>
FORGIUM_AGENT_API_KEY=mg_xxx

Store the key in the host application's secret manager; do not commit it,

include it in a capability manifest, or put it in logs.

2. Configure the integration

If either value is unavailable, stop here and use Request access.

Do not substitute a guessed host, placeholder URL, or another environment's key.

export FORGIUM_AGENT_BASE_URL="https://<public-api-host>"
export FORGIUM_AGENT_API_KEY="mg_xxx"

Confirm the public API is reachable:

curl -fsS "$FORGIUM_AGENT_BASE_URL/health"

Expected response:

{"status":"ok","service":"agent-api"}

3. Send the first message

curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/channels/http/messages" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "integration-smoke-test",
    "message": {
      "type": "text",
      "body": "Hello, can you help me?"
    },
    "metadata": {
      "source": "integration-smoke-test"
    }
  }'

A successful response contains a conversation_id and an assistant message.

This is the completion evidence for a connectivity-only test. Persist the

conversation_id in the host application and send it in later requests to

continue the same conversation.

user_id is an optional opaque identifier and is strongly recommended so

Forgium can attribute AI usage to the individual user within the account. It is

not mandatory during the current client migration and there is no announced

cutoff date. If omitted, usage is still recorded for the account but not for an

individual user within the account.

4. Send a message with an image

Images use binary multipart transport. The payload part is JSON and the

image part is one JPEG, PNG, or WebP file no larger than 4 MiB:

curl -fsS -X POST "$FORGIUM_AGENT_BASE_URL/v1/channels/http/messages" \
  -H "Authorization: Bearer $FORGIUM_AGENT_API_KEY" \
  -F 'payload={"user_id":"integration-image-test","message":{"type":"text","body":"Registrá este comprobante"}};type=application/json' \
  -F 'image=@./receipt.png;type=image/png'

Forgium processes the image in memory and does not store the image, OCR or

Markdown extraction, model reasoning, or confidence. If the operation needs

more fields, answer the clarification in the same conversation; the image

does not need to be uploaded again. Send cancelar to discard a pending

operation without invoking the host application.

Uploading an image alone does not define which business fields to extract. To

receive structured values such as an invoice number, supplier, total, or

transfer reference, the account must have an active capability with an

image_interpretation declaration. See Image-assisted capabilities

for the manifest shape; the host capability endpoint receives the validated

arguments, while the chat response remains the user-facing result.

What the chat receives after image processing

Image interpretation does not add a raw OCR or extracted-fields object to the

public response. The host receives the validated capability arguments through

its capability endpoint, and the chat receives the normal

HttpChannelResponse envelope:

{
  "conversation_id": "conv_xxx",
  "message": {
    "id": "msg_xxx",
    "role": "assistant",
    "type": "text",
    "body": "..."
  }
}

The response behavior is bounded by the outcome:

• Successful read: the assistant responds using the validated result from
  the host capability; it does not expose OCR text or model reasoning.
• Missing required fields: the assistant asks for the missing values and
  keeps a short-lived pending draft. The next message continues the same
  operation.
• Ambiguous operation: the assistant asks what the user wants to do and
  does not invoke a capability.
• Unreadable image or OCR failure: the assistant returns a safe failure
  message and does not invoke the host.
• Host-owned preparation: the response includes the documented interaction
  union for confirmation, selection, or not-found; the host owns the next
  action.

The exact natural-language body can vary by capability result and locale. Hosts

must consume the documented response envelope and interaction discriminator,

not match one fixed assistant sentence.

For an image-assisted mutation workflow, this response is a preparation step:

Forgium returns the host-owned confirmation preview, but the host application

must ask the user for confirmation and execute the mutation itself. Forgium

never executes the final mutation.

{
  "conversation_id": "conv_xxx",
  "message": {
    "id": "msg_xxx",
    "role": "assistant",
    "type": "text",
    "body": "..."
  }
}

5. Select the next integration task

• Register a business capability when the agent needs
  read-only data or a host-owned operation preparation result.
• Read authentication before handling 401 responses or storing the
  key in deployment configuration.
• Read environments before promoting an integration beyond
  development.

Troubleshooting

The OpenAPI contract is authoritative for all request and

response fields. If an agent cannot locate the contract, use the exact commands

in Contract retrieval; do not substitute another

contract. For staging or production, validate the bundle and environment

isolation described in Environments.

For a server-side adapter pattern, error mapping, conversation handling, and

production security checklist, see HTTP integration reference.