The Connector API provides a dedicated REST surface for external systems — CI/CD pipelines, orchestration platforms, custom dashboards — to manage agents programmatically. It uses token-based authentication and capability-based access control to scope what each connector can do.

Authentication

All /connector/* endpoints require a bearer token:

curl http://localhost:8080/connector/reasoners \
  -H "Authorization: Bearer $CONNECTOR_TOKEN"

Configure the token via environment variable or config file:

AGENTFIELD_CONNECTOR_TOKEN=your-secret-token

# agentfield.yaml
connector:
  token: "your-secret-token"
  capabilities:
    - "reasoners:read"
    - "reasoners:write"
    - "versions:read"
    - "versions:write"
    - "restart"

Capabilities

Each connector token can be scoped to specific capabilities:

Capability	Grants
`reasoners:read`	List and get reasoner details
`reasoners:write`	Modify reasoner configuration
`versions:read`	List and get version details
`versions:write`	Update traffic weights
`restart`	Restart specific agent versions

Read-Only Mode

For monitoring dashboards, grant only reasoners:read and versions:read. The connector middleware enforces capability checks on every request.

Endpoints

Manifest

GET /connector/manifest

Returns the connector's capabilities and control plane version. Use this to verify authentication and check what the connector token is authorized to do.

List Reasoners

GET /connector/reasoners

Returns all registered agents (reasoners) with their health status, version, and metadata.

Get Reasoner

GET /connector/reasoners/:id

Returns details for a specific reasoner.

List Versions

GET /connector/reasoners/:id/versions

Returns all registered versions of a reasoner with health status and traffic weights.

Get Version

GET /connector/reasoners/:id/versions/:version

Returns details for a specific version.

Set Traffic Weight

PUT /connector/reasoners/:id/versions/:version/weight

Body:

{
  "weight": 500
}

Updates the traffic weight for a specific version. Weight must be 0–10000. See the Multi-Versioning guide for deployment patterns.

Restart Version

POST /connector/reasoners/:id/versions/:version/restart

Sends a restart signal to a specific versioned agent instance.

List Groups

GET /connector/groups

Returns all agent groups (agents that share the same ID but have different versions).

List Group Nodes

GET /connector/groups/:groupId

Returns all nodes in a specific agent group.

Configuration

Environment Variables

Variable	Type	Default	Description
`AGENTFIELD_CONNECTOR_TOKEN`	string	—	Bearer token for connector authentication
`AGENTFIELD_CONNECTOR_CAPABILITIES`	string	all	Comma-separated list of capabilities

YAML Configuration

connector:
  token: "your-secret-token"
  capabilities:
    - "reasoners:read"
    - "versions:read"
    - "versions:write"
    - "restart"

Example: CI/CD Integration

Use the connector API in your deployment pipeline to manage canary rollouts:

#!/bin/bash
# deploy-canary.sh

CONNECTOR_URL="http://agentfield:8080/connector"
TOKEN="$CONNECTOR_TOKEN"
AGENT_ID="my-agent"
NEW_VERSION="$1"  # e.g., "2.0.0"

# Wait for new version to register and become healthy
echo "Waiting for $AGENT_ID v$NEW_VERSION to be healthy..."
for i in $(seq 1 30); do
  STATUS=$(curl -s -H "Authorization: Bearer $TOKEN" \
    "$CONNECTOR_URL/reasoners/$AGENT_ID/versions/$NEW_VERSION" \
    | jq -r '.health_status')
  [ "$STATUS" = "active" ] && break
  sleep 2
done

# Set canary weight (10%)
curl -X PUT -H "Authorization: Bearer $TOKEN" \
  "$CONNECTOR_URL/reasoners/$AGENT_ID/versions/$NEW_VERSION/weight" \
  -d '{"weight": 100}'

echo "Canary deployed at 10% traffic"

Next Steps

Multi-Versioning — Weighted traffic routing and deployment patterns
Permissions — Access control between agents
Environment Variables — Full configuration reference