# Add and use Services

> Turn an external HTTP API into explicit Agent capabilities with stored Credentials and durable recovery behavior.

A Service is a governed connection to an external HTTP API. It gives each allowed request a stable capability name, bounded input and output schemas, an effect class, and recovery behavior. An Agent binds the Service; a Tool can then expose one or more of its capabilities to a model.

The Service stores no secret text. It references a [Credential](/docs/credentials), and the platform injects that Credential only during an authorized invocation. Rotating the Credential does not require changing or redeploying the Service.

## Before you begin {#before-you-begin}

Create the Credential that authenticates requests, unless the endpoint is public. List the smallest API operations the Agent actually needs. A Service should not expose an unrestricted HTTP client or accept a destination URL from Agent input.

## Add a Service in the Console {#steps}

1. Open **Resources → Services** and choose **Add Service**.
2. Enter a stable Service name and its HTTPS API origin, such as `https://api.github.com`.
3. Choose the authentication method and stored Credential. Bearer, API-key header, Basic, and unauthenticated requests are supported.
4. Add each allowed capability. Give it a narrow name and description, HTTP method, path, request schema, and response schema.
5. Choose the capability's effect. This controls what Constal does if the response is interrupted.
6. Review the maximum response size and choose **Create Service**.

Paths are relative to the configured origin. A path such as `/repos/{owner}/{repo}/issues` reads named values from the capability arguments and safely URL-encodes them. `GET` sends no request body; other supported methods send the arguments as JSON.

## Design capabilities {#capabilities}

Prefer one outcome-oriented capability over a generic request operation. Give it the narrowest practical JSON schema, name only the path parameters the request needs, and describe the result in language a model can distinguish from neighboring capabilities.

## Choose truthful recovery behavior {#recovery}

| Effect | Use when | Interrupted response |
| --- | --- | --- |
| Reads only | The operation cannot change external state | The same call may be repeated |
| Safe change | The provider honors the supplied idempotency key | The same request identity may be retried |
| One-time change | Repeating could duplicate an external effect | The outcome becomes unknown and requires review |

The built-in Service setup deliberately does not offer managed reconciliation. That behavior requires integration code that can query the provider for the authoritative result of an earlier request.

## Use the Service from an Agent {#use-from-agent}

Bind the Service in `constal.agent.json`:

```json constal.agent.json
{
  "bindings": {
    "github": "crn:constal:production:YOUR_TENANT:default:service/github"
  }
}
```

Deterministic Agent code can invoke the accepted capability directly:

```ts
const issues = await ctx.invoke(ctx.resources.github!, "issues.search", {
  owner: "constal-ai",
  repo: "coreagents",
  state: "open",
});
```

To let the model choose the call, project the existing operation as a Tool:

```ts
import { opTool } from "@constal/sdk";

export const searchIssues = opTool("github", "issues.search");
```

The Agent deployment pins the Tool schema and the exact accepted Service contract. It does not create a parallel integration or copy Credential material into the Agent package.

## Verify {#verify}

Open the Service detail page and confirm the capability list, Credential relationship, and Policy attachments. Start a test Run and inspect the journal for the Tool call and underlying Service invocation. For a mutating capability, test the provider's idempotency behavior before enabling it for production Agents.

## Next steps {#next-steps}

Read [Build and use Tools](/docs/resources/tools.md), [Use Resources from Agents](/docs/resources/use.md), and [Scoped bindings](/docs/credentials/scoped-bindings) for customer- or principal-specific Service and Credential resolution.