开源MCP工具

Agent Quickstart

Start the API:

make bootstrap-dev
source .venv/bin/activate
uvicorn grantflow.api.app:app --reload

Discover the agent contract:

export GRANTFLOW_BASE_URL="http://127.0.0.1:8000"

curl "$GRANTFLOW_BASE_URL/.well-known/agent-capabilities.json"
curl "$GRANTFLOW_BASE_URL/.well-known/agent-tools.json"
curl "$GRANTFLOW_BASE_URL/.well-known/agent-recipes.json"

Request self-serve onboarding:

curl -X POST "$GRANTFLOW_BASE_URL/agents/onboarding" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "proposal-worker",
    "auth_type": "api_key",
    "requested_scopes": ["generate:write", "status:read", "quality:read"]
  }'

Request OAuth client credentials and exchange a Bearer token:

curl -X POST "$GRANTFLOW_BASE_URL/agents/onboarding" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "proposal-worker",
    "auth_type": "oauth_client_credentials",
    "requested_scopes": ["generate:write", "status:read", "quality:read"]
  }'

curl -X POST "$GRANTFLOW_BASE_URL/agents/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "client_credentials",
    "client_id": "'"$GRANTFLOW_CLIENT_ID"'",
    "client_secret": "'"$GRANTFLOW_CLIENT_SECRET"'",
    "scope": "generate:write status:read quality:read"
  }'

Register a sandbox agent for sample payloads:

curl -X POST "$GRANTFLOW_BASE_URL/agents/register" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "proposal-worker",
    "agent_type": "workflow_agent",
    "purpose": "Run deterministic GrantFlow smoke workflows"
  }'

The response includes sample_requests.preflight and sample_requests.generate, so an agent can immediately run a safe sandbox workflow.

Full guide: docs/agents/quickstart.md

Self-serve agent keys carry expiry, tenant, and scopes. Agent-critical endpoints enforce tenant_id and scopes when API-key auth is active.

Short-lived runtime sessions are available at POST /agents/session.

Agents can validate X-API-Key or Authorization: Bearer credentials with POST /agents/introspect before calling protected tools.

Agents can rotate or revoke self-serve credentials:

curl -X POST "$GRANTFLOW_BASE_URL/agents/credentials/rotate" \
  -H "Content-Type: application/json" \
  -d '{"credential":"'"$GRANTFLOW_AGENT_CREDENTIAL"'","ttl_seconds":3600}'

curl -X POST "$GRANTFLOW_BASE_URL/agents/credentials/revoke" \
  -H "Content-Type: application/json" \
  -d '{"credential":"'"$GRANTFLOW_AGENT_CREDENTIAL"'","reason":"credential rotation completed"}'

Revocation uses an in-process jti denylist for sandbox/controlled deployments. The revoke response includes revocation_scope: "in_process" and restart_safe: false so agents read this limitation without consulting docs. Multi-replica production should enforce revocation at the gateway layer.

Run an external agent conformance smoke:

python -m grantflow.agents.conformance --base-url "$GRANTFLOW_BASE_URL"

Core Workflow

1. Discover capabilities and tools.
2. Onboard credentials or register a sandbox agent identity.
3. Run donor/readiness preflight.
4. Start deterministic generation with an idempotency key.
5. Poll status or consume webhook callbacks.
6. Inspect quality, grounding, citations, and audit events.
7. Export reviewable deliverables and evidence packs.