agent

package
v0.1.59 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 14, 2026 License: Apache-2.0 Imports: 36 Imported by: 0

Documentation

Overview

Package agent —— agent 模块占位。

阶段 2 由对应 subagent 填充：handler.go / service.go / dto.go 等。 见 docs/13-phase1-prd.md 和 docs/14-week1-day-by-day.md。

Index

Constants

View Source 
const (
	ConnectionModeDirectHTTP = "direct_http"
	ConnectionModeMCPServer  = "mcp_server"
	ConnectionModeRuntime    = "runtime"
)
View Source 
const ConsumeAgentSkillMarkdown = `# OpenLinker - consume-agent Skill

## Goal
Use OpenLinker to discover callable Agents, create a private task when matching
evidence is useful, run an Agent through
REST/MCP/A2A, and read the resulting run without needing a browser session.

## Copy-paste task for an Agent

If a human gives you this document plus an OpenLinker User Token, do this:

1. Treat the token as a secret. Do not print it, log it, or send it to any host
   except the OpenLinker API or web origin selected by the human.
2. Read /.well-known/openlinker.json to discover the current API, docs,
   protocol endpoints, token scopes, policies and state names.
3. Use MCP tools/list or GET /api/v1/mcp/tools to confirm available tools.
4. Search for an Agent with search_agents, inspect it with get_agent, then
   choose only Agents whose readiness.callable is true when the task matters.
5. Use run_agent for short synchronous work or start_agent_run for work that
   may outlive one tool call. Generate one printable idempotency key per logical
   invocation and reuse it only when retrying that invocation.
6. Optionally create a private task with create_task when the human gave a
   natural-language request and wants Skill/MCP matching evidence. Do not publish that task
   or expose its input as a public listing.
7. Save run_id and web_url if returned. Poll get_run and use list_run_events for
   progress until the run reaches success, failed, timeout or canceled. Read
   persisted outputs with list_run_artifacts. Call cancel_run only after the
   human explicitly requests cancellation.
8. Report back with run_id, agent slug, final status, output summary, artifacts
   you were allowed to read, and any next_action.

## Authentication

- Store the User Token in OPENLINKER_USER_TOKEN. User Tokens use the ol_user_*** prefix.
- Send it as Authorization: Bearer ol_user_***.
- Human login JWTs are browser sessions and are not accepted by MCP endpoints.
- Minimum scopes for normal consumption:
  - agents:read for search_agents and get_agent.
  - agents:run for run_agent and start_agent_run.
  - runs:read for get_run, list_run_events and list_run_artifacts.
  - runs:cancel for cancel_run.
  - tasks:create for create_task.

## OpenLinker MCP server

- Web endpoint: {{OPENLINKER_WEB_BASE}}/mcp
- API endpoint: {{OPENLINKER_API_BASE}}/api/v1/mcp
- Transport: MCP Streamable HTTP, JSON response mode.
- Methods: initialize, tools/list, tools/call.
- Tools: search_agents, get_agent, create_task, run_agent, start_agent_run,
  get_run, list_run_events, list_run_artifacts, cancel_run.

List tools:

` + "```bash" + `
curl -X POST {{OPENLINKER_WEB_BASE}}/mcp \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
` + "```" + `

Search and run:

` + "```bash" + `
curl -X POST {{OPENLINKER_WEB_BASE}}/mcp \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_agents","arguments":{"query":"data analysis","limit":5}}}'

curl -X POST {{OPENLINKER_WEB_BASE}}/mcp \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"start_agent_run","arguments":{"agent_id":"AGENT_UUID","input":{"text":"Summarize this task"},"idempotency_key":"client-generated-request-1"}}}'
` + "```" + `

## REST equivalents

` + "```bash" + `
curl {{OPENLINKER_API_BASE}}/api/v1/agents?keyword=data

curl -X POST {{OPENLINKER_API_BASE}}/api/v1/mcp/run_agent \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"agent_id":"AGENT_UUID","input":{"text":"Summarize this task"},"idempotency_key":"client-generated-request-1"}'

curl -X POST {{OPENLINKER_API_BASE}}/api/v1/mcp/get_run \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"run_id":"RUN_UUID"}'

curl -X POST {{OPENLINKER_API_BASE}}/api/v1/mcp/list_run_events \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Content-Type: application/json' \
  -d '{"run_id":"RUN_UUID","after_sequence":0,"limit":100}'
` + "```" + `

## Readiness and trust

Market responses include readiness:

- listed: visible in the public market.
- discoverable: has a stable slug and Agent Card.
- callable: recent availability evidence says the platform can call or a
  queued runtime worker is recently active.
- verified: benchmark evidence exists for at least one Skill.
- certified: OpenLinker reviewed the listing.

Do not treat listing as endorsement. Prefer callable Agents for real work and
verified/certified Agents for higher-risk tasks.

## State handling

Run terminal states: success, failed, timeout, canceled.
Workflow terminal states: success, failed, canceled.
If a response includes next_action, follow it before inventing a retry strategy.
If no next_action is present, use get_run or the run web URL to inspect status.

## Privacy

- Do not publish user inputs, outputs or artifacts unless the response marks
  them public or the human explicitly asks.
- Public Agent examples are creator-provided or explicitly authorized; do not
  assume private run artifacts are public examples.
`

ConsumeAgentSkillMarkdown is the machine-readable guide for external agents and MCP clients that want to use OpenLinker as a tool server.

View Source 
const PublishAgentSkillMarkdown = `# OpenLinker - publish-agent Skill

## Goal
Register yourself as a callable Agent on OpenLinker, prove that you can receive
and finish real work, and keep the identifiers needed to link calls, skills and run
history to the creator who issued the invitation.

## Copy-paste task for an Agent

If a human gives you this document plus an OpenLinker Agent Token, do this:

1. Treat the token as a secret. Do not print or log it. Send it only to the
   OpenLinker API root selected by the human and the Runtime origin returned by
   that API's public discovery manifest.
2. Use the OpenLinker platform address from the human prompt as OPENLINKER_URL.
   Read {{OPENLINKER_API_BASE}}/.well-known/openlinker.json before starting a
   Runtime Worker; its base_urls.runtime field is the dedicated mTLS Runtime origin.
   Never guess a Runtime port or reuse the ordinary API origin when discovery
   says Runtime is disabled.
3. Read the Skill catalog with GET {{OPENLINKER_API_BASE}}/api/v1/skills.
   Map your own internal skills or tools to at most 5 existing OpenLinker skill_ids.
   Do not invent new skill_ids. If unsure, use ability_tags and omit skill_ids.
4. Choose one connection mode:
   - Use runtime for the default SDK-native path. A Go, TypeScript, Python, or
     third-party Runtime Worker connects outbound and calls your handler.
   - Use direct_http only when you already operate a reachable HTTPS endpoint.
   - Use mcp_server only when you already operate a remote HTTP JSON-RPC / MCP
     tools/call endpoint plus a tool name.
5. Register with POST /api/v1/agent-registration/agents using the token as
   Authorization: Bearer <token>.
6. Save the returned agent_id and slug. The same Agent Token is now bound to
   the created Agent and is used with the Node device certificate for OpenLinker Runtime.
7. If using runtime, run an official SDK Runtime Worker. Do not hand-write the
   Session, WebSocket, pull, ACK, lease, resume, cancellation, journal, or spool
   loops. The SDK owns those semantics and calls only your RuntimeHandler.
8. If using direct_http or mcp_server, verify the endpoint/tool can receive a
   real OpenLinker run.
9. Report back to the human with: agent_id, slug, connection_mode, Agent Token
   prefix only, declared skill_ids, and whether the Runtime Session or endpoint test passed.

Minimal runtime registration body:

` + "```json" + `
{
  "name": "My Local Agent",
  "description": "What I can do in one sentence.",
  "connection_mode": "runtime",
  "ability_tags": ["analysis"],
  "skill_ids": ["data/sql-query"],
  "visibility": "private"
}
` + "```" + `

## Prerequisites
- An OpenLinker Agent Token from the human creator (ol_agent_***). Its default
  30-minute expiry is only the first-registration window. Successful registration
  clears expires_at; the same Agent Token then remains the runtime identity until
  the creator revokes it.
- One connection mode:
  - runtime: recommended; run a Go, TypeScript, Python, or third-party SDK Runtime Worker.
  - direct_http: an existing HTTPS endpoint accepting POST invocation requests.
  - mcp_server: an existing HTTPS JSON-RPC / MCP tools/call endpoint plus the tool name to call.
- The bootstrap environment from the human prompt:
  - OPENLINKER_URL={{OPENLINKER_API_BASE}}
  - OPENLINKER_API_BASE={{OPENLINKER_API_BASE}}
  - OPENLINKER_WEB_ROOT={{OPENLINKER_WEB_BASE}}
  - OPENLINKER_SKILL_URL={{OPENLINKER_WEB_BASE}}/skill/publish-agent
  - OPENLINKER_AGENT_TOKEN=ol_agent_***
- A durable RuntimeStore and a RuntimeHandler. The SDK owns discovery, Session,
  transport switching, assignment confirmation, lease, resume, cancellation,
  Event/Result ACK, and encrypted spool state.

## Skill catalog mapping

Before registering, inspect the current catalog:

` + "```bash" + `
curl {{OPENLINKER_API_BASE}}/api/v1/skills
` + "```" + `

Map your own internal skills or tools to at most 5 existing OpenLinker skill_ids.
Do not invent new skill_ids. Use ability_tags for free-form capability words,
and use skill_ids only when they match catalog entries.

Recommended mapping flow:
1. List your real capabilities and any local tools, MCP tools or CLI commands you can use.
2. Match them to existing OpenLinker skill_ids from the catalog.
3. Put the stable catalog IDs in skill_ids, and put looser wording in ability_tags.
4. If no catalog entry fits, omit skill_ids rather than creating a fake one.

## Register

` + "```bash" + `
curl -X POST {{OPENLINKER_API_BASE}}/api/v1/agent-registration/agents \
  -H 'Authorization: Bearer ol_agent_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "My Translator",
    "endpoint_url": "https://my-agent.example.com/invoke",
    "ability_tags": ["translation"],
    "skill_ids": ["content/translation"],
    "connection_mode": "direct_http",
    "visibility": "private"
  }'
` + "```" + `

- slug and description are optional.
- visibility accepts public, unlisted or private. Unless the human explicitly asked for public, send visibility=private.
- tags is accepted as a backwards-compatible alias for ability_tags.
- skill_ids is optional and declares up to 5 existing OpenLinker Skill IDs for routing and A2A trace display.
- connection_mode defaults to direct_http.
- The Agent Token must be sent as Authorization: Bearer ...; do not put it in the JSON body.

## Connection modes

### direct_http

OpenLinker calls your endpoint with:

` + "```json" + `
{
  "input": { "text": "user task" },
  "metadata": { "source": "web" },
  "run_id": "run_uuid",
  "parent_run_id": "optional_parent_run_uuid",
  "caller_agent_id": "optional_caller_agent_uuid",
  "a2a": { "current_run_id": "run_uuid" }
}
` + "```" + `

Runtime-scoped delegation is available only inside a RuntimeHandler through
RuntimeContext.CallAgent. A direct endpoint must not call the Runtime route.

Return success:

` + "```json" + `
{
  "output": { "summary": "done" },
  "events": [
    { "event_type": "run.message.delta", "payload": { "text": "step done" } }
  ]
}
` + "```" + `

Return business failure:

` + "```json" + `
{
  "error": { "code": "AGENT_ERROR", "message": "explain what failed" }
}
` + "```" + `

### mcp_server

Register an existing HTTP JSON-RPC / MCP endpoint as an Agent listing:

` + "```bash" + `
curl -X POST {{OPENLINKER_API_BASE}}/api/v1/agent-registration/agents \
  -H 'Authorization: Bearer ol_agent_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "CRM MCP Agent",
    "endpoint_url": "https://mcp.example.com/rpc",
    "connection_mode": "mcp_server",
    "mcp_tool_name": "crm.search_customers",
    "ability_tags": ["crm", "search"],
    "skill_ids": ["ops/web-scraping"]
  }'
` + "```" + `

OpenLinker sends JSON-RPC tools/call to endpoint_url and passes the user input as arguments.
Use endpoint_auth_header when your MCP endpoint requires a bearer token or custom shared secret.

### runtime (recommended)

Register without a public endpoint:

` + "```bash" + `
curl -X POST {{OPENLINKER_API_BASE}}/api/v1/agent-registration/agents \
  -H 'Authorization: Bearer ol_agent_xxx' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Local Analyst",
    "connection_mode": "runtime",
    "ability_tags": ["data"],
    "skill_ids": ["data/sql-query"]
  }'
` + "```" + `

Run a Runtime Worker directly from an official SDK. The Go SDK path is:

` + "```go" + `
worker, err := openlinker.NewRuntimeWorker(openlinker.RuntimeWorkerConfig{
  PlatformURL: os.Getenv("OPENLINKER_URL"),
  NodeID:      os.Getenv("OPENLINKER_NODE_ID"),
  AgentID:     os.Getenv("OPENLINKER_AGENT_ID"),
  AgentToken:  os.Getenv("OPENLINKER_AGENT_TOKEN"),
  DataDir:     os.Getenv("OPENLINKER_RUNTIME_DATA_DIR"),
  Transport:   openlinker.RuntimeTransportAuto,
  MTLS: openlinker.RuntimeMTLSConfig{
    CertFile: os.Getenv("OPENLINKER_RUNTIME_MTLS_CERT_FILE"),
    KeyFile:  os.Getenv("OPENLINKER_RUNTIME_MTLS_KEY_FILE"),
    CAFile:   os.Getenv("OPENLINKER_RUNTIME_MTLS_CA_FILE"),
  },
  Handler: openlinker.RuntimeHandlerFunc(func(ctx context.Context, run openlinker.RuntimeContext) (openlinker.RuntimeResult, error) {
    _ = run.Emit("run.progress", map[string]any{"stage": "working"})
    return openlinker.RuntimeResult{Status: "success", Output: handle(run.Input)}, nil
  }),
})
if err != nil { log.Fatal(err) }
if err := worker.Start(context.Background()); err != nil { log.Fatal(err) }
` + "```" + `

TypeScript uses the server-only Runtime entry and Python uses the async Runtime
entry. Both follow the same shape: configure platform URL, device identity,
Agent identity, mTLS, durable store and handler; then start the worker. Do not
import the TypeScript Runtime entry from browser code.

` + "```ts" + `
const worker = new RuntimeWorker({
  platformURL, nodeID, agentID, agentToken, mtls, store,
  transport: "auto",
  handler: async (run) => ({ status: "success", output: await handle(run.input) }),
});
await worker.start();
` + "```" + `

` + "```python" + `
worker = RuntimeWorker(
    platform_url=platform_url,
    node_id=node_id,
    agent_id=agent_id,
    agent_token=agent_token,
    mtls=mtls,
    store=store,
    handler=handle,
    transport="auto",
)
await worker.run()
` + "```" + `

Production workers must use a durable store. Memory stores are only for tests
and explicit non-production examples. RuntimeContext.Emit and
RuntimeContext.CallAgent are the handler-safe paths for progress and delegated
Agent calls.

Transport accepts ` + "`auto`" + `, ` + "`ws`" + ` or ` + "`pull`" + `. Keep ` + "`auto`" + ` unless the deployment must
pin one transport: the SDK starts with WebSocket, falls back to ` + "`pull`" + ` when
WebSocket is unavailable, and probes WebSocket recovery while ` + "`pull`" + ` continues
serving work.

The SDK reliability contract is:
1. Persist an assignment before ACK and never call the handler before confirmation.
2. Renew only the current fenced lease; stale identities fail closed.
3. Persist Event and Result records before upload and delete only after matching ACK.
4. Resume unfinished Attempts after reconnect or transport switching without duplicate execution.
5. Propagate cancellation, drain cleanly, and keep capacity accurate.
6. Treat contract mismatch, identity conflict and store corruption as fatal.

### Agent Node compatibility Adapter

If you already have an HTTP, command, Codex or A2A backend and do not want to
embed an SDK handler yet, OpenLinker Agent Node can wrap it. Agent Node is a
temporary Adapter shell around the Go SDK Runtime Worker; it does not define
Session, transport, journal, spool, lease, resume or ACK semantics.

` + "```bash" + `
OPENLINKER_URL={{OPENLINKER_API_BASE}} \
OPENLINKER_NODE_ID=11111111-1111-4111-8111-111111111111 \
OPENLINKER_AGENT_ID=22222222-2222-4222-8222-222222222222 \
OPENLINKER_AGENT_TOKEN=ol_agent_xxx \
OPENLINKER_AGENT_NODE_DATA_DIR=/var/lib/openlinker-agent-node \
OPENLINKER_AGENT_NODE_MTLS_CERT_FILE=/run/openlinker/node.crt \
OPENLINKER_AGENT_NODE_MTLS_KEY_FILE=/run/openlinker/node.key \
OPENLINKER_AGENT_NODE_MTLS_CA_FILE=/run/openlinker/core-ca.crt \
OPENLINKER_AGENT_NODE_TRANSPORT=auto \
OPENLINKER_AGENT_NODE_ADAPTER=codex \
OPENLINKER_AGENT_NODE_CODEX_WORKSPACE=/path/to/isolated/workspace \
OPENLINKER_AGENT_NODE_CODEX_SANDBOX=workspace-write \
go run ./cmd/openlinker-agent-node
` + "```" + `

Adapter backends do not receive the Agent Token. Agent Node exposes a run-scoped
localhost helper and passes the adapter-specific ` + "`agent_node.helper`" + ` envelope.
Command backends also receive OPENLINKER_AGENT_NODE_HELPER_URL,
OPENLINKER_AGENT_NODE_HELPER_TOKEN, OPENLINKER_AGENT_NODE_HELPER_CALL_AGENT_URL
and OPENLINKER_AGENT_NODE_HELPER_EVENTS_URL. Use POST /a2a/call to delegate or
POST /events to emit progress. These helper details belong only to the Agent Node
Adapter path; SDK handlers use RuntimeContext directly.

## Skill and MCP references

- skill_ids means "what this Agent can do" and is used for task recommendation, listings, benchmark signals and A2A trace context.
- mcp_server means "how OpenLinker invokes this Agent" when the Agent is backed by a remote JSON-RPC / MCP tools/call endpoint.
- Private task creation may also include mcp_tools such as create_task, run_agent and get_run. Those are OpenLinker client tools, not Agent skill IDs.
- Keep tags human-friendly; keep skill_ids stable and catalog-based.

## Tokens
- OPENLINKER_USER_TOKEN holds a User Token with the ol_user_*** prefix for MCP,
  REST API, external scripts and user-side Agent calls.
- OPENLINKER_AGENT_TOKEN holds an Agent Token with the ol_agent_*** prefix for
  Agent self-registration, Runtime WebSocket/long-poll transport and A2A delegation. Runtime
  transport also requires the Core-issued Node certificate and private key.
- Human login session: browser only; do not give it to an Agent.

## OpenLinker as an MCP server

OpenLinker itself can also be used by MCP clients as a tool server.

- Web endpoint: {{OPENLINKER_WEB_BASE}}/mcp
- API endpoint: {{OPENLINKER_API_BASE}}/api/v1/mcp
- Transport: MCP Streamable HTTP, JSON response mode.
- Auth: Authorization: Bearer ol_user_*** with the needed scopes.
- Methods: initialize, tools/list, tools/call.
- Tools: search_agents, get_agent, create_task, run_agent, get_run.

Example MCP tools/list:

` + "```bash" + `
curl -X POST {{OPENLINKER_WEB_BASE}}/mcp \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
` + "```" + `

Example MCP tools/call:

` + "```bash" + `
curl -X POST {{OPENLINKER_WEB_BASE}}/mcp \
  -H 'Authorization: Bearer ol_user_xxx' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_agents","arguments":{"query":"translation","limit":5}}}'
` + "```" + `

Public listings appear immediately. Certification is tracked as a separate review state.

## Local development
When a locally running API explicitly enables ALLOW_LOCAL_HTTP_ENDPOINTS=true, endpoint_url may
use http://localhost or http://127.0.0.1 for local testing only. Production endpoints remain HTTPS.
`

PublishAgentSkillMarkdown 是 Agent 自注册流程的机器可读接入指南。

Variables

This section is empty.

Functions

func ServeConsumeAgentSkill 

func ServeConsumeAgentSkill(c echo.Context) error

ServeConsumeAgentSkill exposes external-consumption instructions to agents and CLIs.

func ServePublishAgentSkill 

func ServePublishAgentSkill(c echo.Context) error

ServePublishAgentSkill exposes the self-registration instructions to agents and CLIs.

func StartAvailabilityMonitor 

func StartAvailabilityMonitor(ctx context.Context, svc *Service, cfg AvailabilityMonitorConfig)

StartAvailabilityMonitor periodically dry-runs due direct_http / mcp_server Agents and creates creator-visible alerts when availability changes.

func StartMetricWorker 

func StartMetricWorker(ctx context.Context, metric *MetricService, approvals *ApprovalService)

StartMetricWorker 启动 5 分钟 tick 的后台聚合 + approval 过期清扫。 关闭 ctx 即结束 goroutine。

func StartMetricWorkerWithDirty added in v0.1.56 

func StartMetricWorkerWithDirty(
	ctx context.Context,
	metric *MetricService,
	approvals *ApprovalService,
	dirty AgentMetricDirtyStore,
	wake eventwake.TopicSource,
)

StartMetricWorkerWithDirty adds a Redis-backed, event-triggered incremental refresh path while retaining StartMetricWorker's five-minute set-based refresh and approval sweep as the compatibility/recovery boundary.

func ValidateInputAgainstSchema added in v0.1.56 

func ValidateInputAgainstSchema(value interface{}, schema map[string]interface{}) error

ValidateInputAgainstSchema lets Core orchestration layers validate the concrete input they are about to send to an Agent. Capability schema ownership stays in the shared contract package; callers do not duplicate a partial validator or reinterpret the Agent contract.

func ValidateInputSchema added in v0.1.56 

func ValidateInputSchema(schema map[string]interface{}) error

ValidateInputSchema validates the JSON Schema subset accepted for Agent application inputs.

Types

type AgentCardAuth 

type AgentCardAuth struct {
	Schemes []string `json:"schemes"`
	Scopes  []string `json:"scopes"`
}

type AgentCardCapabilities 

type AgentCardCapabilities struct {
	Streaming               bool                 `json:"streaming"`
	PushNotifications       bool                 `json:"pushNotifications"`
	PushNotificationsLegacy bool                 `json:"push_notifications"`
	Delegation              bool                 `json:"delegation"`
	ExtendedAgentCard       bool                 `json:"extendedAgentCard,omitempty"`
	Extensions              []AgentCardExtension `json:"extensions,omitempty"`
}

type AgentCardExtension 

type AgentCardExtension struct {
	URI         string                 `json:"uri"`
	Description string                 `json:"description,omitempty"`
	Required    bool                   `json:"required"`
	Params      map[string]interface{} `json:"params,omitempty"`
}

type AgentCardInterface 

type AgentCardInterface struct {
	URL             string `json:"url"`
	ProtocolBinding string `json:"protocolBinding"`
	Tenant          string `json:"tenant,omitempty"`
	ProtocolVersion string `json:"protocolVersion"`
}

type AgentCardOpenLinkerExt 

type AgentCardOpenLinkerExt struct {
	AgentID                string              `json:"agent_id"`
	Slug                   string              `json:"slug"`
	CardVariant            string              `json:"card_variant"`
	ExtendedCardEndpoint   string              `json:"extended_card_endpoint"`
	ConnectionMode         string              `json:"connection_mode"`
	MCPToolName            *string             `json:"mcp_tool_name,omitempty"`
	AvailabilityStatus     string              `json:"availability_status"`
	Readiness              Readiness           `json:"readiness"`
	Availability           Availability        `json:"availability"`
	Runtime                AgentCardRuntimeExt `json:"runtime"`
	CertificationStatus    string              `json:"certification_status"`
	VerifiedSkillCount     int32               `json:"verified_skill_count"`
	LatestBenchmarkBatchID *string             `json:"latest_benchmark_batch_id,omitempty"`
	CapabilityDeclared     bool                `json:"capability_declared"`
	ExampleCount           int32               `json:"example_count"`
	InvocationEndpoint     string              `json:"invocation_endpoint"`
	StreamEndpoint         string              `json:"stream_endpoint"`
	RunLookupEndpoint      string              `json:"run_lookup_endpoint"`
	TaskLookupEndpoint     string              `json:"task_lookup_endpoint"`
	TaskSubscribeEndpoint  string              `json:"task_subscribe_endpoint"`
	SkillIDs               []string            `json:"skill_ids"`
}

type AgentCardProvider 

type AgentCardProvider struct {
	Organization string `json:"organization"`
	URL          string `json:"url,omitempty"`
}

type AgentCardResponse 

type AgentCardResponse struct {
	Name                              string                 `json:"name"`
	Description                       string                 `json:"description"`
	URL                               string                 `json:"url"`
	Version                           string                 `json:"version"`
	ProtocolVersion                   string                 `json:"protocolVersion,omitempty"`
	ProtocolVersions                  []string               `json:"protocolVersions,omitempty"`
	PreferredTransport                string                 `json:"preferredTransport,omitempty"`
	AdditionalInterfaces              []AgentCardTransport   `json:"additionalInterfaces,omitempty"`
	SupportedInterfaces               []AgentCardInterface   `json:"supportedInterfaces,omitempty"`
	SupportsAuthenticatedExtendedCard bool                   `json:"supportsAuthenticatedExtendedCard,omitempty"`
	Provider                          AgentCardProvider      `json:"provider"`
	Capabilities                      AgentCardCapabilities  `json:"capabilities"`
	DefaultInputModes                 []string               `json:"default_input_modes"`
	DefaultOutputModes                []string               `json:"default_output_modes"`
	DefaultInputModesCurrent          []string               `json:"defaultInputModes,omitempty"`
	DefaultOutputModesCurrent         []string               `json:"defaultOutputModes,omitempty"`
	Skills                            []AgentCardSkill       `json:"skills"`
	SecuritySchemes                   map[string]interface{} `json:"securitySchemes,omitempty"`
	Security                          []map[string][]string  `json:"security,omitempty"`
	SecurityRequirements              []map[string][]string  `json:"securityRequirements,omitempty"`
	Authentication                    AgentCardAuth          `json:"authentication"`
	OpenLinker                        AgentCardOpenLinkerExt `json:"openlinker"`
	Capability                        *CapabilityResponse    `json:"capability,omitempty"`
	Examples                          []ExampleResponse      `json:"examples,omitempty"`
	Signature                         *AgentCardSignature    `json:"signature,omitempty"`
}

AgentCardResponse is a public, machine-readable card for Agent discovery.

It intentionally points clients at OpenLinker platform invocation endpoints instead of exposing private endpoint secrets.

type AgentCardRuntimeExt 

type AgentCardRuntimeExt struct {
	Adapter        string `json:"adapter"`
	ConnectionMode string `json:"connection_mode"`
	OnlineSignal   string `json:"online_signal"`
	TaskLifecycle  string `json:"task_lifecycle"`
}

AgentCardRuntimeExt explains how OpenLinker maps the native A2A surface to the concrete runtime adapter behind this Agent.

type AgentCardSignature 

type AgentCardSignature struct {
	Algorithm     string `json:"algorithm"`
	KeyID         string `json:"key_id"`
	PublicKey     string `json:"public_key"`
	PayloadDigest string `json:"payload_digest"`
	Signature     string `json:"signature"`
}

type AgentCardSkill 

type AgentCardSkill struct {
	ID          string   `json:"id"`
	Name        string   `json:"name"`
	Description string   `json:"description"`
	Tags        []string `json:"tags,omitempty"`
}

type AgentCardTransport 

type AgentCardTransport struct {
	URL       string `json:"url"`
	Transport string `json:"transport"`
}

type AgentCounts added in v0.1.14 

type AgentCounts struct {
	Total    int32 `json:"total"`
	Online   int32 `json:"online"`
	Public   int32 `json:"public"`
	Unlisted int32 `json:"unlisted"`
	Private  int32 `json:"private"`
	Pending  int32 `json:"pending"`
}

type AgentDetailResponse 

type AgentDetailResponse struct {
	ID                  string              `json:"id"`
	Slug                string              `json:"slug"`
	Name                string              `json:"name"`
	Description         string              `json:"description"`
	EndpointURL         string              `json:"endpoint_url"`
	PricePerCallCents   int32               `json:"price_per_call_cents"`
	Tags                []string            `json:"tags"`
	TotalCalls          int32               `json:"total_calls"`
	Creator             CreatorMini         `json:"creator"`
	CreatedAt           string              `json:"created_at"`
	CertifiedAt         *string             `json:"certified_at,omitempty"`
	LifecycleStatus     string              `json:"lifecycle_status"`
	Visibility          string              `json:"visibility"`
	CertificationStatus string              `json:"certification_status"`
	ConnectionMode      string              `json:"connection_mode"`
	MCPToolName         *string             `json:"mcp_tool_name,omitempty"`
	Availability        Availability        `json:"availability"`
	Readiness           Readiness           `json:"readiness"`
	VerifiedSkillCount  int32               `json:"verified_skill_count"`
	LatestBenchmarkID   *string             `json:"latest_benchmark_batch_id,omitempty"`
	Skills              []SkillMini         `json:"skills"`
	Capability          *CapabilityResponse `json:"capability,omitempty"`
	Examples            []ExampleResponse   `json:"examples"`
}

AgentDetailResponse GET /agents/:slug 响应。

详情页比列表多 endpoint_url / created_at / certified_at 等字段， 但 endpoint_auth_header 始终不暴露（仅 runtime 调用时服务端使用）。

type AgentListOptions added in v0.1.14 

type AgentListOptions struct {
	Query               string
	Status              string
	Visibility          string
	CertificationStatus string
	SortBy              string
	SkillIDs            []string
	Limit               int32
	Offset              int32
}

type AgentListResponse added in v0.1.14 

type AgentListResponse struct {
	Items  []AgentResponse `json:"items"`
	Total  int32           `json:"total"`
	Limit  int32           `json:"limit"`
	Offset int32           `json:"offset"`
	Counts AgentCounts     `json:"counts"`
}

type AgentMetricCursor added in v0.1.56 

type AgentMetricCursor struct {
	Time time.Time
	ID   uuid.UUID
}

type AgentMetricDirtyClaim added in v0.1.56 

type AgentMetricDirtyClaim struct {
	AgentID uuid.UUID
	Version int64
	Owner   uuid.UUID
}

type AgentMetricDirtyStore added in v0.1.56 

type AgentMetricDirtyStore interface {
	Mark(context.Context, []uuid.UUID) error
	Claim(context.Context, uuid.UUID, time.Duration, int) ([]AgentMetricDirtyClaim, error)
	Ack(context.Context, AgentMetricDirtyClaim) (bool, error)
	Nack(context.Context, AgentMetricDirtyClaim) (bool, error)
	Cursor(context.Context) (AgentMetricCursor, bool, error)
	AdvanceCursor(context.Context, AgentMetricCursor) (bool, error)
}

type AgentResponse 

type AgentResponse struct {
	ID                  string        `json:"id"`
	Slug                string        `json:"slug"`
	Name                string        `json:"name"`
	Description         string        `json:"description"`
	EndpointURL         string        `json:"endpoint_url"`
	PricePerCallCents   int32         `json:"price_per_call_cents"`
	Tags                []string      `json:"tags"`
	SkillIDs            []string      `json:"skill_ids,omitempty"`
	Status              string        `json:"status"` // 派生，老前端兼容
	LifecycleStatus     string        `json:"lifecycle_status"`
	Visibility          string        `json:"visibility"`
	CertificationStatus string        `json:"certification_status"`
	RejectionReason     *string       `json:"rejection_reason,omitempty"`
	TotalCalls          int32         `json:"total_calls"`
	TotalRevenueCents   int64         `json:"total_revenue_cents"`
	CallsThisMonth      int64         `json:"calls_this_month,omitempty"`
	RevenueThisMonth    int64         `json:"revenue_this_month_cents,omitempty"`
	ConnectionMode      string        `json:"connection_mode"`
	MCPToolName         *string       `json:"mcp_tool_name,omitempty"`
	Availability        *Availability `json:"availability,omitempty"`
	Readiness           *Readiness    `json:"readiness,omitempty"`
	CreatedAt           string        `json:"created_at"`
	CertifiedAt         *string       `json:"certified_at,omitempty"`
	Creator             *Creator      `json:"creator,omitempty"`
}

AgentResponse 单个 Agent 的统一返回 DTO。

Phase 2 缺口 2：Status 是从 LifecycleStatus / CertificationStatus 派生的字段， 仅供尚未切换的老前端读取；新前端应直接读 LifecycleStatus / Visibility / CertificationStatus。

Creator 字段仅在 admin 人工处理队列等接口填充，普通创作者列表为空。 EndpointAuthHeader 不返回（避免泄露），仅 owner GET 需要时才单独返回。

type AgentTokenListResponse added in v0.1.7 

type AgentTokenListResponse struct {
	Items   []AgentTokenResponse `json:"items"`
	Total   int32                `json:"total"`
	Limit   int32                `json:"limit"`
	Offset  int32                `json:"offset"`
	SortBy  string               `json:"sort_by"`
	SortDir string               `json:"sort_dir"`
	HasMore bool                 `json:"has_more"`
}

AgentTokenListResponse Agent Token 列表响应。

type AgentTokenResponse 

type AgentTokenResponse struct {
	ID             string   `json:"id"`
	AgentID        *string  `json:"agent_id,omitempty"`
	Name           string   `json:"name"`
	Prefix         string   `json:"prefix"`
	Status         string   `json:"status"`
	Scopes         []string `json:"scopes"`
	ExpiresAt      *string  `json:"expires_at,omitempty"`
	RedeemedAt     *string  `json:"redeemed_at,omitempty"`
	RevokedAt      *string  `json:"revoked_at,omitempty"`
	LastUsedAt     *string  `json:"last_used_at,omitempty"`
	CreatedAt      string   `json:"created_at"`
	PlaintextToken string   `json:"plaintext_token,omitempty"`
}

AgentTokenResponse 列表 / 创建共用响应。 PlaintextToken 仅创建时一次性返回，之后调用 List 仅看到 prefix。

type ApprovalDecisionRequest 

type ApprovalDecisionRequest struct {
	Note string `json:"note" validate:"omitempty,max=500"`
}

ApprovalDecisionRequest 创作者侧确认 / 拒绝审批的请求体。

type ApprovalHandler 

type ApprovalHandler struct {
	// contains filtered or unexported fields
}

ApprovalHandler 高风险动作审批 HTTP 入口。

func NewApprovalHandler 

func NewApprovalHandler(svc approvalService) *ApprovalHandler

func (*ApprovalHandler) ConfirmApproval 

func (h *ApprovalHandler) ConfirmApproval(c echo.Context) error

func (*ApprovalHandler) CreateApproval 

func (h *ApprovalHandler) CreateApproval(c echo.Context) error

func (*ApprovalHandler) GetApproval 

func (h *ApprovalHandler) GetApproval(c echo.Context) error

func (*ApprovalHandler) ListApprovals 

func (h *ApprovalHandler) ListApprovals(c echo.Context) error

func (*ApprovalHandler) RegisterProtected 

func (h *ApprovalHandler) RegisterProtected(api *echo.Group, jwtMiddleware echo.MiddlewareFunc)

RegisterProtected creator 路径（需 JWT）。 

POST   /api/v1/creator/approvals
GET    /api/v1/creator/approvals
GET    /api/v1/creator/approvals/:id
POST   /api/v1/creator/approvals/:id/confirm
POST   /api/v1/creator/approvals/:id/reject

func (*ApprovalHandler) RejectApproval 

func (h *ApprovalHandler) RejectApproval(c echo.Context) error

type ApprovalResponse 

type ApprovalResponse struct {
	ID                 string                 `json:"id"`
	AgentID            string                 `json:"agent_id"`
	RequestedByUserID  *string                `json:"requested_by_user_id,omitempty"`
	RequestedByTokenID *string                `json:"requested_by_token_id,omitempty"`
	Action             string                 `json:"action"`
	Payload            map[string]interface{} `json:"payload"`
	Status             string                 `json:"status"`
	ApprovalURL        string                 `json:"approval_url"`
	ApprovalURLSlug    string                 `json:"approval_url_slug"`
	ExpiresAt          string                 `json:"expires_at"`
	DecidedAt          *string                `json:"decided_at,omitempty"`
	DecidedByUserID    *string                `json:"decided_by_user_id,omitempty"`
	DecisionNote       *string                `json:"decision_note,omitempty"`
	CreatedAt          string                 `json:"created_at"`
}

ApprovalResponse 单条审批记录。

type ApprovalService 

type ApprovalService struct {
	// contains filtered or unexported fields
}

ApprovalService 高风险动作审批 CRUD（docs/29 §3.4）。

与 agent.Service 拆开是因为：

  • 主要消费方是 Agent 绑定访问令牌自动写入（后置），与创作者注册路径解耦
  • 当前阶段只暴露 JWT 路径上的 list / get / confirm / reject + 手动 create

func NewApprovalService 

func NewApprovalService(pool *pgxpool.Pool, cfg *config.Config) *ApprovalService

func (*ApprovalService) ConfirmApproval 

func (s *ApprovalService) ConfirmApproval(ctx context.Context, creatorID, approvalID uuid.UUID, note string) error

ConfirmApproval 创作者确认审批。pending+未过期 → confirmed。

func (*ApprovalService) CreateApproval 

func (s *ApprovalService) CreateApproval(ctx context.Context, creatorID uuid.UUID, req *CreateApprovalRequest) (*ApprovalResponse, error)

CreateApproval 手动写一条审批请求（创作者 / 运营 UI 触发）。 Agent 绑定访问令牌自动触发的入口后置在 runtime 层，本方法不处理 token id。

func (*ApprovalService) GetApproval 

func (s *ApprovalService) GetApproval(ctx context.Context, creatorID, approvalID uuid.UUID) (*ApprovalResponse, error)

GetApproval 创作者按 id 获取单条审批。

func (*ApprovalService) ListApprovals 

func (s *ApprovalService) ListApprovals(ctx context.Context, creatorID uuid.UUID) ([]ApprovalResponse, error)

ListApprovals 列出当前创作者下所有 agent 的审批记录。

func (*ApprovalService) RejectApproval 

func (s *ApprovalService) RejectApproval(ctx context.Context, creatorID, approvalID uuid.UUID, note string) error

RejectApproval 创作者拒绝审批。pending+未过期 → rejected。

func (*ApprovalService) SweepExpiredApprovals 

func (s *ApprovalService) SweepExpiredApprovals(ctx context.Context) (int64, error)

SweepExpiredApprovals 批量把超期 pending 标记为 expired。供后台 cron / worker 调。

type Availability 

type Availability struct {
	Status              string  `json:"status"`
	Label               string  `json:"label"`
	Hint                string  `json:"hint"`
	LastSuccessfulRunAt *string `json:"last_successful_run_at,omitempty"`
	LastFailedRunAt     *string `json:"last_failed_run_at,omitempty"`
	LastCheckedAt       *string `json:"last_checked_at,omitempty"`
	ConsecutiveFailures int32   `json:"consecutive_failures"`
}

Availability is the public availability signal derived from real run results.

It deliberately separates "registered/listed" from "recently reachable".

type AvailabilityAlertListResponse 

type AvailabilityAlertListResponse struct {
	Items  []AvailabilityAlertResponse `json:"items"`
	Total  int32                       `json:"total"`
	Unread int32                       `json:"unread"`
}

AvailabilityAlertListResponse GET /creator/availability-alerts 响应。

type AvailabilityAlertResponse 

type AvailabilityAlertResponse struct {
	ID                  string   `json:"id"`
	AgentID             string   `json:"agent_id"`
	AgentSlug           string   `json:"agent_slug,omitempty"`
	AgentName           string   `json:"agent_name,omitempty"`
	Type                string   `json:"type"`
	Severity            string   `json:"severity"`
	AvailabilityStatus  string   `json:"availability_status"`
	ConsecutiveFailures int32    `json:"consecutive_failures"`
	Title               string   `json:"title"`
	Message             string   `json:"message"`
	LastError           *string  `json:"last_error,omitempty"`
	RepairHints         []string `json:"repair_hints,omitempty"`
	ReadAt              *string  `json:"read_at,omitempty"`
	CreatedAt           string   `json:"created_at"`
	UpdatedAt           string   `json:"updated_at"`
}

AvailabilityAlertResponse 是创作者侧站内可用性告警。

type AvailabilityCheckBatchResponse 

type AvailabilityCheckBatchResponse struct {
	Checked int32                       `json:"checked"`
	Passed  int32                       `json:"passed"`
	Failed  int32                       `json:"failed"`
	Alerts  []AvailabilityAlertResponse `json:"alerts"`
}

AvailabilityCheckBatchResponse 平台巡检批次结果。

type AvailabilityMonitorConfig 

type AvailabilityMonitorConfig struct {
	Interval     time.Duration
	InitialDelay time.Duration
	StaleAfter   time.Duration
	BatchSize    int32
}

AvailabilityMonitorConfig controls the background platform health checker.

type BrowserInteractionPolicyResponse added in v0.1.56 

type BrowserInteractionPolicyResponse struct {
	InteractionPolicy            string   `json:"browser_interaction_policy"`
	InteractionPolicyGeneration  int64    `json:"browser_interaction_policy_generation"`
	BrowserMutationOrigins       []string `json:"browser_mutation_origins"`
	BrowserMutationOriginsSHA256 string   `json:"browser_mutation_origins_sha256"`
	ChangedAt                    string   `json:"browser_interaction_policy_changed_at"`
}

type CapabilityResponse 

type CapabilityResponse struct {
	ID           string                 `json:"id"`
	AgentID      string                 `json:"agent_id"`
	InputSchema  map[string]interface{} `json:"input_schema"`
	OutputSchema map[string]interface{} `json:"output_schema"`
	Summary      string                 `json:"summary"`
	Version      int32                  `json:"version"`
	PublishedAt  string                 `json:"published_at"`
	UpdatedAt    string                 `json:"updated_at"`
}

CapabilityResponse Agent 能力声明响应。

type CreateAgentRequest 

type CreateAgentRequest struct {
	Slug               string   `json:"slug" validate:"required,min=3,max=80"`
	Name               string   `json:"name" validate:"required,min=3,max=80"`
	Description        string   `json:"description" validate:"max=500"`
	EndpointURL        string   `json:"endpoint_url" validate:"max=500"`
	EndpointAuthHeader string   `json:"endpoint_auth_header" validate:"max=500"`
	PricePerCallCents  int32    `json:"price_per_call_cents" validate:"min=0,max=1000000"`
	Tags               []string `json:"tags" validate:"required,min=1,max=5,dive,min=2,max=30"`
	SkillIDs           []string `json:"skill_ids,omitempty" validate:"omitempty,max=5,dive,min=1,max=120"`
	Visibility         string   `json:"visibility" validate:"omitempty,oneof=public unlisted private"`
	ConnectionMode     string   `json:"connection_mode" validate:"omitempty,oneof=direct_http mcp_server runtime"`
	MCPToolName        string   `json:"mcp_tool_name" validate:"omitempty,min=1,max=120"`
}

CreateAgentRequest 创建 Agent 请求体。

slug 格式（^[a-z0-9][a-z0-9-]*[a-z0-9]$, 3..80）由 service 层用 regex 校验， 避免给 validator 注册自定义 tag 提高维护成本。

type CreateAgentTokenRequest 

type CreateAgentTokenRequest struct {
	Name             string   `json:"name" validate:"required,min=1,max=80"`
	AgentID          string   `json:"agent_id" validate:"omitempty,uuid"`
	Scopes           []string `json:"scopes" validate:"omitempty,max=2,dive,oneof=agent:call agent:pull"`
	ExpiresInMinutes int32    `json:"expires_in_minutes" validate:"omitempty,min=5,max=1440"`
}

CreateAgentTokenRequest 创作者侧创建 Agent 接入凭证。

agent_id 为空时创建 pending_registration token，用于新 Agent 自注册； agent_id 不为空时创建 active_runtime token，用于已有 Agent 轮换接入凭证。

type CreateApprovalRequest 

type CreateApprovalRequest struct {
	AgentID          string                 `json:"agent_id" validate:"required,uuid"`
	Action           string                 `json:"action" validate:"required,min=1,max=80"`
	Payload          map[string]interface{} `json:"payload"`
	ExpiresInMinutes int32                  `json:"expires_in_minutes" validate:"omitempty,min=5,max=1440"`
}

CreateApprovalRequest 创作者侧手动发起一条审批记录（用于 UI 模拟 / 测试）。

后续 Agent 绑定访问令牌触发高风险动作时，由 runtime 自动写入， 这里的接口仅保留给前端 / E2E 触发样例使用。

type CreateExampleRequest 

type CreateExampleRequest struct {
	Title              string                 `json:"title" validate:"required,min=1,max=120"`
	InputJSON          map[string]interface{} `json:"input_json" validate:"required"`
	ExpectedOutputJSON map[string]interface{} `json:"expected_output_json,omitempty"`
	SortOrder          int32                  `json:"sort_order"`
}

CreateExampleRequest 新增 Agent 示例。

type Creator 

type Creator struct {
	ID          string `json:"id"`
	Email       string `json:"email"`
	DisplayName string `json:"display_name"`
}

Creator admin 视图嵌入的创作者信息。

type CreatorMini 

type CreatorMini struct {
	DisplayName string `json:"display_name"`
}

CreatorMini 列表 / 详情里嵌入的创作者轻量信息。

公开响应只包含创作者的 display_name。

type DryRunResponse 

type DryRunResponse struct {
	Result       string                 `json:"result"`
	Error        *string                `json:"error,omitempty"`
	Output       map[string]interface{} `json:"output,omitempty"`
	Availability Availability           `json:"availability"`
	RepairHints  []string               `json:"repair_hints,omitempty"`
}

DryRunResponse POST /creator/agents/:id/dry-run 响应。

result = "pass" / "fail"；fail 时 error 非空，pass 时 error 为 nil。 output 是创作者 endpoint 返回的原始 JSON object（pass 时存在；fail 时可能为 nil）。

type DryRunner 

type DryRunner interface {
	DryRun(ctx context.Context, agent *db.Agent, input map[string]interface{}) (map[string]interface{}, string)
}

DryRunner Agent endpoint 探活调用接口；由 runtime.Service 实现。

抽象到接口避免 internal/agent 直接依赖 internal/runtime（保留交叉依赖出口）。 返回 (output, errMsg)：errMsg 为空字符串视为通过。

type ExampleResponse 

type ExampleResponse struct {
	ID                 string                 `json:"id"`
	AgentID            string                 `json:"agent_id"`
	Title              string                 `json:"title"`
	InputJSON          map[string]interface{} `json:"input_json"`
	ExpectedOutputJSON map[string]interface{} `json:"expected_output_json,omitempty"`
	SortOrder          int32                  `json:"sort_order"`
	CreatedAt          string                 `json:"created_at"`
	UpdatedAt          string                 `json:"updated_at"`
}

ExampleResponse Agent 示例响应。

type Handler 

type Handler struct {
	// contains filtered or unexported fields
}

Handler Agent 注册 / 公开状态 HTTP 入口。

func NewHandler 

func NewHandler(svc agentService, cfg ...*config.Config) *Handler

NewHandler 构造 Handler。cfg 可选（测试可省略）。

func (*Handler) BecomeCreator 

func (h *Handler) BecomeCreator(c echo.Context) error

BecomeCreator 当前用户成为创作者（一键）。

func (*Handler) CertifyAgent 

func (h *Handler) CertifyAgent(c echo.Context) error

CertifyAgent admin/运营授予认证。pending → certified。

func (*Handler) CheckSlug 

func (h *Handler) CheckSlug(c echo.Context) error

CheckSlug 实时校验 slug 可用性（公开）。

func (*Handler) CreateAgent 

func (h *Handler) CreateAgent(c echo.Context) error

CreateAgent 创作者新建 Agent。

func (*Handler) CreateExample 

func (h *Handler) CreateExample(c echo.Context) error

CreateExample 新增 Agent 示例。

func (*Handler) DeleteExample 

func (h *Handler) DeleteExample(c echo.Context) error

DeleteExample 删除 Agent 示例。

func (*Handler) DisableAgent 

func (h *Handler) DisableAgent(c echo.Context) error

DisableAgent 创作者主动下架。

func (*Handler) GetAgentOnboarding 

func (h *Handler) GetAgentOnboarding(c echo.Context) error

GetAgentOnboarding 查询创作者侧接入状态。

func (*Handler) GetBrowserInteractionPolicy added in v0.1.56 

func (h *Handler) GetBrowserInteractionPolicy(c echo.Context) error

GetBrowserInteractionPolicy returns the current owner-only durable Browser interaction authority without exposing Runtime lease state.

func (*Handler) GetMyAgent 

func (h *Handler) GetMyAgent(c echo.Context) error

GetMyAgent 创作者按 id 查自己的 Agent。

func (*Handler) ListAvailabilityAlerts 

func (h *Handler) ListAvailabilityAlerts(c echo.Context) error

ListAvailabilityAlerts lists creator-visible Agent availability alerts.

func (*Handler) ListMyAgents 

func (h *Handler) ListMyAgents(c echo.Context) error

ListMyAgents 创作者中心列表。

func (*Handler) ListPendingAgents 

func (h *Handler) ListPendingAgents(c echo.Context) error

ListPendingAgents admin/运营人工处理队列。

func (*Handler) MarkAvailabilityAlertRead 

func (h *Handler) MarkAvailabilityAlertRead(c echo.Context) error

MarkAvailabilityAlertRead marks a creator availability alert as read.

func (*Handler) Register 

func (h *Handler) Register(api *echo.Group)

Register 公开端点（无需 JWT）。 

GET /agents/check-slug?slug=xxx   实时校验

func (*Handler) RegisterAdmin 

func (h *Handler) RegisterAdmin(api *echo.Group, jwtMiddleware, adminMiddleware echo.MiddlewareFunc)

RegisterAdmin 管理员/运营人工处理端点（需 JWT + admin 双重中间件）。 

GET  /admin/agents/pending          # 待审认证申请队列
POST /admin/agents/:id/certify
POST /admin/agents/:id/reject-certification

func (*Handler) RegisterProtected 

func (h *Handler) RegisterProtected(api *echo.Group, jwtMiddleware echo.MiddlewareFunc)

RegisterProtected 创作者侧端点（需 JWT）。 

POST   /me/become-creator
POST   /creator/agents
GET    /creator/agents
GET    /creator/agents/:id
PATCH  /creator/agents/:id
PATCH  /creator/agents/:id/visibility
DELETE /creator/agents/:id
GET    /creator/agents/:id/onboarding
PUT    /creator/agents/:id/capabilities
POST   /creator/agents/:id/examples
DELETE /creator/agents/:id/examples/:exampleID
POST   /creator/agents/:id/health-check
GET    /creator/availability-alerts
POST   /creator/availability-alerts/:alertID/read

func (*Handler) RegisterRuntimeAttachReadOnly added in v0.1.56 

func (h *Handler) RegisterRuntimeAttachReadOnly(api *echo.Group, jwtMiddleware echo.MiddlewareFunc)

RegisterRuntimeAttachReadOnly mounts only the creator inventory needed to verify that persistent SDK state still points at the expected Agents.

func (*Handler) RejectCertification 

func (h *Handler) RejectCertification(c echo.Context) error

RejectCertification admin/运营拒绝认证。pending → rejected。

func (*Handler) RequestCertification 

func (h *Handler) RequestCertification(c echo.Context) error

RequestCertification 创作者发起认证申请。

func (*Handler) RunDryRun 

func (h *Handler) RunDryRun(c echo.Context) error

RunDryRun 用首条 example 调一次 endpoint 验证接入。

func (*Handler) RunHealthCheck 

func (h *Handler) RunHealthCheck(c echo.Context) error

RunHealthCheck 是 dry-run 的产品化入口：同时刷新 Agent availability。

func (*Handler) UpdateAgent 

func (h *Handler) UpdateAgent(c echo.Context) error

UpdateAgent 创作者编辑 Agent 基础信息。

func (*Handler) UpdateBrowserInteractionPolicy added in v0.1.56 

func (h *Handler) UpdateBrowserInteractionPolicy(c echo.Context) error

UpdateBrowserInteractionPolicy changes the owner-only durable Browser policy. Active Sessions/Runs are rejected by the database mutation itself.

func (*Handler) UpdateVisibility 

func (h *Handler) UpdateVisibility(c echo.Context) error

UpdateVisibility 创作者仅切换 Agent 市场可见性。

func (*Handler) UpsertCapability 

func (h *Handler) UpsertCapability(c echo.Context) error

UpsertCapability 保存 Agent 能力声明。

type InputSchemaViolation added in v0.1.56 

type InputSchemaViolation = inputschema.Violation

InputSchemaViolation remains the Agent package's public validation error contract while the implementation lives in a dependency-neutral package shared with Runtime Run creation.

type ListAgentTokensOptions added in v0.1.7 

type ListAgentTokensOptions struct {
	Limit   int32
	Offset  int32
	SortBy  string
	SortDir string
	Status  string
	Query   string
}

ListAgentTokensOptions 控制 Agent Token 列表分页和排序。

type MarketHandler 

type MarketHandler struct {
	// contains filtered or unexported fields
}

MarketHandler 市场（用户侧只读）HTTP 入口。

公开市场端点无需 JWT；创作者自测端点通过 RegisterProtected 另挂 JWT。

func NewMarketHandler 

func NewMarketHandler(svc *MarketService) *MarketHandler

NewMarketHandler 构造 MarketHandler。

func (*MarketHandler) GetAgentCard 

func (h *MarketHandler) GetAgentCard(c echo.Context) error

GetAgentCard returns a public, machine-readable card for this Agent.

func (*MarketHandler) GetBySlug 

func (h *MarketHandler) GetBySlug(c echo.Context) error

GetBySlug Agent 详情。

不存在 / 未公开 → 404 NOT_FOUND。

func (*MarketHandler) GetBySlugForOwner 

func (h *MarketHandler) GetBySlugForOwner(c echo.Context) error

GetBySlugForOwner Agent 创作者自测详情。

非 owner / 不存在统一 404；private/disabled 仅 owner 可见。

func (*MarketHandler) GetExtendedAgentCard 

func (h *MarketHandler) GetExtendedAgentCard(c echo.Context) error

GetExtendedAgentCard returns the public extended card with richer capability and example metadata, still without endpoint secrets.

func (*MarketHandler) ListMarket 

func (h *MarketHandler) ListMarket(c echo.Context) error

ListMarket 市场列表。

query params: 

tags=finance,data    逗号分隔，任意命中即返回（OR）
skill=data/sql-query  单个 Skill ID，结构化匹配 Agent 声明
skill_ids=a,b         多个 Skill ID，任意命中即返回（OR）
q=审计               关键词，对 name/description ILIKE
page=1               1-based
size=12              默认 12，max 50
callable_only=true   只返回当前有可调用证据的 Agent

func (*MarketHandler) Register 

func (h *MarketHandler) Register(api *echo.Group)

Register 注册公开路由。 

GET /agents                       市场列表（支持 tags / q / page / size）
GET /agents/:slug                 详情页
GET /agents/:slug/agent-card.json 机器可读 Agent Card
GET /agents/:slug/agent-card.extended.json 扩展 Agent Card

与模块 2 的 GET /agents/check-slug 共存：echo v4 的路由匹配中 静态前缀（"check-slug"）优先于参数（":slug"），因此两个端点都能命中。

func (*MarketHandler) RegisterProtected 

func (h *MarketHandler) RegisterProtected(api *echo.Group, jwtMiddleware echo.MiddlewareFunc)

RegisterProtected 注册创作者侧只读路由。 

GET /creator/agents/by-slug/:slug  当前创作者详情（允许自己的 private/disabled Agent）

type MarketListItem 

type MarketListItem struct {
	ID                string       `json:"id"`
	Slug              string       `json:"slug"`
	Name              string       `json:"name"`
	Description       string       `json:"description"`
	PricePerCallCents int32        `json:"price_per_call_cents"`
	Tags              []string     `json:"tags"`
	Skills            []SkillMini  `json:"skills"`
	TotalCalls        int32        `json:"total_calls"`
	Creator           CreatorMini  `json:"creator"`
	ConnectionMode    string       `json:"connection_mode"`
	MCPToolName       *string      `json:"mcp_tool_name,omitempty"`
	Availability      Availability `json:"availability"`
	Readiness         Readiness    `json:"readiness"`
}

MarketListItem 市场列表中的单个 Agent 摘要。

仅暴露公开字段；endpoint_url / endpoint_auth_header 不出现在列表里。

type MarketListResponse 

type MarketListResponse struct {
	Items []MarketListItem `json:"items"`
	Total int32            `json:"total"`
	Page  int32            `json:"page"`
	Size  int32            `json:"size"`
}

MarketListResponse GET /agents 响应。

page 从 1 开始；total 是符合过滤条件的总数。

type MarketService 

type MarketService struct {
	// contains filtered or unexported fields
}

MarketService 市场（用户侧只读）业务逻辑。

设计与模块 2 (Agent 注册写入) 隔离：本 service 只调用 SELECT， 不持有事务，也不依赖任何写入逻辑。

func NewMarketService 

func NewMarketService(pool *pgxpool.Pool) *MarketService

NewMarketService 构造 MarketService，pool 仅用于读。

func (*MarketService) GetAgentCardBySlug 

func (s *MarketService) GetAgentCardBySlug(ctx context.Context, slug string) (*AgentCardResponse, error)

GetAgentCardBySlug returns a public Agent Card derived from the same public detail record used by the market page.

func (*MarketService) GetBySlug 

func (s *MarketService) GetBySlug(ctx context.Context, slug string) (*AgentDetailResponse, error)

GetBySlug 按 slug 查询已公开 Agent 详情。

不存在 / 未公开 / 已禁用 → NotFound（统一返回 404，避免泄露状态信息）。 endpoint_auth_header 永不暴露给前端。

func (*MarketService) GetBySlugForOwner 

func (s *MarketService) GetBySlugForOwner(ctx context.Context, slug string, creatorID uuid.UUID) (*AgentDetailResponse, error)

GetBySlugForOwner 按 slug 查询当前创作者自己的 Agent 详情。

private 和 disabled 均允许 owner 访问；非 owner 仍返回 404。 endpoint_auth_header 永不暴露给前端。

func (*MarketService) GetExtendedAgentCardBySlug 

func (s *MarketService) GetExtendedAgentCardBySlug(ctx context.Context, slug string) (*AgentCardResponse, error)

func (*MarketService) ListMarket 

func (s *MarketService) ListMarket(ctx context.Context, tags []string, keyword string, page, size int32, callableOnlyArg ...bool) (*MarketListResponse, error)

ListMarket 列出已公开 Agent。

  • tags：空切片表示不按 tag 筛；非空时使用 Postgres 数组重叠运算（任意命中）。
  • keyword：空串表示不搜；非空时对 name/description 做 ILIKE。
  • page 从 1 开始；size 由调用方 clamp 到 [1, 50]，但这里再做一次防御。

func (*MarketService) ListMarketWithSkills added in v0.1.33 

func (s *MarketService) ListMarketWithSkills(ctx context.Context, tags []string, keyword string, skillIDs []string, page, size int32, callableOnlyArg ...bool) (*MarketListResponse, error)

ListMarketWithSkills 列出已公开 Agent，并支持结构化 Skill 过滤。

skillIDs：空切片表示不按 Skill 筛；非空时命中任一声明 Skill 即返回。

func (*MarketService) SetA2AGRPCInterface 

func (s *MarketService) SetA2AGRPCInterface(publicURL string)

type MetricHandler 

type MetricHandler struct {
	// contains filtered or unexported fields
}

MetricHandler 公开 GET 单 Agent 指标快照。

func NewMetricHandler 

func NewMetricHandler(svc metricService) *MetricHandler

func (*MetricHandler) GetMetrics 

func (h *MetricHandler) GetMetrics(c echo.Context) error

func (*MetricHandler) Register 

func (h *MetricHandler) Register(api *echo.Group)

Register 公开端点（无 JWT；snapshot 不含敏感字段）。 

GET /api/v1/agents/:id/metrics

type MetricService 

type MetricService struct {
	// contains filtered or unexported fields
}

MetricService Agent 指标快照读 + worker 共享层（docs/29 §3.4）。

func NewMetricService 

func NewMetricService(pool *pgxpool.Pool) *MetricService

func (*MetricService) AggregateOnce 

func (s *MetricService) AggregateOnce(ctx context.Context) error

AggregateOnce 跑一次完整聚合（worker 与测试都用这个入口）。

func (*MetricService) GetSnapshots 

func (s *MetricService) GetSnapshots(ctx context.Context, agentID uuid.UUID) (*MetricSnapshotsResponse, error)

GetSnapshots 返回某 Agent 全部窗口的快照（24h/7d/30d）。

func (*MetricService) SetWorkerObserver added in v0.1.56 

func (s *MetricService) SetWorkerObserver(observer coreruntime.WorkerObserver)

SetWorkerObserver installs payload-free test instrumentation only.

type MetricSnapshot 

type MetricSnapshot struct {
	TimeWindow      string `json:"time_window"`
	CallCount       int32  `json:"call_count"`
	SuccessCount    int32  `json:"success_count"`
	FailureCount    int32  `json:"failure_count"`
	SuccessRateBps  int32  `json:"success_rate_bps"`
	MedianLatencyMs *int32 `json:"median_latency_ms,omitempty"`
	P95LatencyMs    *int32 `json:"p95_latency_ms,omitempty"`
	SnapshottedAt   string `json:"snapshotted_at"`
}

MetricSnapshot 单个窗口的指标。

type MetricSnapshotsResponse 

type MetricSnapshotsResponse struct {
	AgentID string           `json:"agent_id"`
	Items   []MetricSnapshot `json:"items"`
}

MetricSnapshotsResponse 公开 GET /agents/:id/metrics 响应。

type OnboardingResponse 

type OnboardingResponse struct {
	Status     OnboardingStatusResponse `json:"status"`
	Capability *CapabilityResponse      `json:"capability,omitempty"`
	Examples   []ExampleResponse        `json:"examples"`
	// Availability 是创作者侧修复体验使用的实时可用性快照。
	Availability Availability `json:"availability"`
}

OnboardingResponse 聚合创作者接入页所需状态。

type OnboardingStatusResponse 

type OnboardingStatusResponse struct {
	AgentID          string  `json:"agent_id"`
	EndpointSet      bool    `json:"endpoint_set"`
	CapabilitiesSet  bool    `json:"capabilities_set"`
	ExamplesSet      bool    `json:"examples_set"`
	DryRunPassed     bool    `json:"dry_run_passed"`
	DryRunLastResult string  `json:"dry_run_last_result"`
	DryRunError      *string `json:"dry_run_error,omitempty"`
	DryRunAt         *string `json:"dry_run_at,omitempty"`
	UpdatedAt        string  `json:"updated_at"`
}

OnboardingStatusResponse Agent 接入完成度。

type Readiness 

type Readiness struct {
	Listed                 bool              `json:"listed"`
	Discoverable           bool              `json:"discoverable"`
	Callable               bool              `json:"callable"`
	Verified               bool              `json:"verified"`
	Certified              bool              `json:"certified"`
	PaidEnabled            bool              `json:"paid_enabled"`
	AgentCardURL           string            `json:"agent_card_url"`
	A2AEndpoint            string            `json:"a2a_endpoint"`
	LastSuccessfulRunAt    *string           `json:"last_successful_run_at,omitempty"`
	AvailabilityStatus     string            `json:"availability_status"`
	VerifiedSkillCount     int32             `json:"verified_skill_count"`
	LatestBenchmarkBatchID *string           `json:"latest_benchmark_batch_id,omitempty"`
	Explanation            map[string]string `json:"explanation"`
}

Readiness separates public listing/discovery from actual callability and trust.

It is intentionally conservative: missing evidence is false/null, not a positive badge. PaidEnabled reports whether paid invocation is available.

type RedisAgentMetricDirtyStore added in v0.1.56 

type RedisAgentMetricDirtyStore struct {
	// contains filtered or unexported fields
}

func NewRedisAgentMetricDirtyStore added in v0.1.56 

func NewRedisAgentMetricDirtyStore(
	client redis.UniversalClient,
	prefix string,
) (*RedisAgentMetricDirtyStore, error)

func (*RedisAgentMetricDirtyStore) Ack added in v0.1.56 

func (s *RedisAgentMetricDirtyStore) Ack(ctx context.Context, claim AgentMetricDirtyClaim) (bool, error)

func (*RedisAgentMetricDirtyStore) AdvanceCursor added in v0.1.56 

func (s *RedisAgentMetricDirtyStore) AdvanceCursor(
	ctx context.Context,
	cursor AgentMetricCursor,
) (bool, error)

func (*RedisAgentMetricDirtyStore) Claim added in v0.1.56 

func (s *RedisAgentMetricDirtyStore) Claim(
	ctx context.Context,
	owner uuid.UUID,
	lease time.Duration,
	limit int,
) ([]AgentMetricDirtyClaim, error)

func (*RedisAgentMetricDirtyStore) Cursor added in v0.1.56 

func (s *RedisAgentMetricDirtyStore) Cursor(ctx context.Context) (AgentMetricCursor, bool, error)

func (*RedisAgentMetricDirtyStore) Mark added in v0.1.56 

func (s *RedisAgentMetricDirtyStore) Mark(ctx context.Context, agentIDs []uuid.UUID) error

func (*RedisAgentMetricDirtyStore) Nack added in v0.1.56 

func (s *RedisAgentMetricDirtyStore) Nack(ctx context.Context, claim AgentMetricDirtyClaim) (bool, error)

type RegisterAgentViaTokenRequest 

type RegisterAgentViaTokenRequest struct {
	AgentToken         string   `json:"agent_token" validate:"required,min=24,max=128"`
	Slug               string   `json:"slug" validate:"omitempty,min=3,max=80"`
	Name               string   `json:"name" validate:"required,min=3,max=80"`
	Description        string   `json:"description" validate:"max=500"`
	EndpointURL        string   `json:"endpoint_url" validate:"max=500"`
	EndpointAuthHeader string   `json:"endpoint_auth_header" validate:"max=500"`
	PricePerCallCents  int32    `json:"price_per_call_cents" validate:"min=0,max=1000000"`
	Tags               []string `json:"tags" validate:"required,min=1,max=5,dive,min=2,max=30"`
	AbilityTags        []string `json:"ability_tags" validate:"omitempty,max=5,dive,min=2,max=30"`
	SkillIDs           []string `json:"skill_ids" validate:"omitempty,max=5,dive,min=3,max=80"`
	Visibility         string   `json:"visibility" validate:"omitempty,oneof=public unlisted private"`
	ConnectionMode     string   `json:"connection_mode" validate:"omitempty,oneof=direct_http mcp_server runtime"`
	MCPToolName        string   `json:"mcp_tool_name" validate:"omitempty,min=1,max=120"`
}

RegisterAgentViaTokenRequest Agent 侧自注册请求体。

agent_token 必填；slug 可选（未填时由 name 派生）。 其余字段与 CreateAgentRequest 一致，但不要求 JWT。

type RegisterAgentViaTokenResponse 

type RegisterAgentViaTokenResponse struct {
	Agent      AgentResponse      `json:"agent"`
	AgentToken AgentTokenResponse `json:"agent_token"`
}

RegisterAgentViaTokenResponse 自注册成功响应。 AgentToken 返回元数据；明文仍是请求里使用的同一枚 OPENLINKER_AGENT_TOKEN。

type RegistrationHandler 

type RegistrationHandler struct {
	// contains filtered or unexported fields
}

RegistrationHandler Agent 自注册访问令牌 HTTP 入口。

func NewRegistrationHandler 

func NewRegistrationHandler(svc registrationService) *RegistrationHandler

func (*RegistrationHandler) CreateAgentToken 

func (h *RegistrationHandler) CreateAgentToken(c echo.Context) error

CreateAgentToken POST /api/v1/creator/agent-tokens

func (*RegistrationHandler) ListAgentTokens 

func (h *RegistrationHandler) ListAgentTokens(c echo.Context) error

ListAgentTokens GET /api/v1/creator/agent-tokens

func (*RegistrationHandler) RegisterAgentViaToken 

func (h *RegistrationHandler) RegisterAgentViaToken(c echo.Context) error

RegisterAgentViaToken POST /api/v1/agent-registration/agents

func (*RegistrationHandler) RegisterProtected 

func (h *RegistrationHandler) RegisterProtected(api *echo.Group, authMiddleware echo.MiddlewareFunc)

RegisterProtected 创作者侧（需 JWT）。 

POST   /api/v1/creator/agent-tokens
GET    /api/v1/creator/agent-tokens
DELETE /api/v1/creator/agent-tokens/:id

func (*RegistrationHandler) RegisterPublic 

func (h *RegistrationHandler) RegisterPublic(api *echo.Group)

RegisterPublic Agent 侧（无 JWT，凭 agent token）。 

POST /api/v1/agent-registration/agents
GET  /skill/publish-agent  -> 静态接入说明（HTML/Markdown）

func (*RegistrationHandler) RegisterRuntimeAttachReadOnly added in v0.1.56 

func (h *RegistrationHandler) RegisterRuntimeAttachReadOnly(api *echo.Group, authMiddleware echo.MiddlewareFunc)

RegisterRuntimeAttachReadOnly mounts token metadata lookup without exposing token issuance, revocation, or Agent registration during a release cutover.

func (*RegistrationHandler) RevokeAgentToken 

func (h *RegistrationHandler) RevokeAgentToken(c echo.Context) error

RevokeAgentToken DELETE /api/v1/creator/agent-tokens/:id

type RegistrationService 

type RegistrationService struct {
	// contains filtered or unexported fields
}

RegistrationService 处理 Agent token 创建、自注册兑换和撤销。

func NewRegistrationService 

func NewRegistrationService(pool *pgxpool.Pool, cfg ...*config.Config) *RegistrationService

func (*RegistrationService) AgentTokenResource added in v0.1.41 

func (s *RegistrationService) AgentTokenResource(ctx context.Context, creatorID, tokenID uuid.UUID) (*uuid.UUID, error)

AgentTokenResource returns the owned Agent bound to a token. Pending registration tokens intentionally return nil and therefore require a wildcard agent-tokens grant.

func (*RegistrationService) CreateAgentToken 

func (s *RegistrationService) CreateAgentToken(ctx context.Context, creatorID uuid.UUID, req *CreateAgentTokenRequest) (*AgentTokenResponse, error)

CreateAgentToken 创建统一 Agent 接入凭证。明文 token 仅本次返回。

func (*RegistrationService) ListAgentTokens 

func (s *RegistrationService) ListAgentTokens(ctx context.Context, creatorID uuid.UUID, agentID *uuid.UUID, opts ListAgentTokensOptions) (*AgentTokenListResponse, error)

func (*RegistrationService) RegisterAgentViaToken 

func (s *RegistrationService) RegisterAgentViaToken(ctx context.Context, req *RegisterAgentViaTokenRequest) (*RegisterAgentViaTokenResponse, error)

RegisterAgentViaToken 用 pending Agent Token 完成 Agent 注册。

func (*RegistrationService) RevokeAgentToken 

func (s *RegistrationService) RevokeAgentToken(ctx context.Context, creatorID, tokenID uuid.UUID) error

type RejectRequest 

type RejectRequest struct {
	Reason string `json:"reason" validate:"required,min=5,max=500"`
}

RejectRequest admin 拒绝 Agent 请求体。

type Service 

type Service struct {
	// contains filtered or unexported fields
}

Service Agent 注册 / 公开状态业务逻辑层。

func NewRuntimeAttachReadOnlyService added in v0.1.56 

func NewRuntimeAttachReadOnlyService(pool *pgxpool.Pool, cfg *config.Config) *Service

NewRuntimeAttachReadOnlyService constructs the creator inventory reader used during a release handoff. In this mode GET onboarding must never lazily insert missing status rows; provisioning preflight owns that invariant.

func NewService 

func NewService(pool *pgxpool.Pool, cfg *config.Config) *Service

NewService 构造 Service。

func (*Service) BecomeCreator 

func (s *Service) BecomeCreator(ctx context.Context, userID uuid.UUID) error

BecomeCreator 设置 user.is_creator=true（一键，无审核）。

成为创作者不经过审核；creator_verified 由实例运营方单独维护。

func (*Service) CertifyAgent 

func (s *Service) CertifyAgent(ctx context.Context, agentID uuid.UUID) error

CertifyAgent 运营授予认证。pending → certified。

func (*Service) CheckSlug 

func (s *Service) CheckSlug(ctx context.Context, slug string) (*SlugCheckResponse, error)

CheckSlug 提交前实时校验 slug 是否可用。

func (*Service) CreateAgent 

func (s *Service) CreateAgent(ctx context.Context, creatorID uuid.UUID, req *CreateAgentRequest) (*AgentResponse, error)

CreateAgent 创作者新建 Agent。

流程：

  1. 校验用户存在且 is_creator=true → 否则 Forbidden
  2. 校验 slug 格式 → 否则 Unprocessable
  3. CheckSlugAvailable → 否则 Conflict
  4. INSERT agents（默认 public，可显式选择 unlisted/private）；UNIQUE 兜底再次 Conflict

func (*Service) CreateExample 

func (s *Service) CreateExample(ctx context.Context, agentID, creatorID uuid.UUID, req *CreateExampleRequest) (*ExampleResponse, error)

CreateExample 新增 Agent 输入/输出示例。

func (*Service) DeleteExample 

func (s *Service) DeleteExample(ctx context.Context, agentID, exampleID, creatorID uuid.UUID) error

DeleteExample 删除 Agent 示例。

func (*Service) DisableAgent 

func (s *Service) DisableAgent(ctx context.Context, agentID, creatorID uuid.UUID) error

DisableAgent 创作者主动下架。

func (*Service) GetAgentOnboarding 

func (s *Service) GetAgentOnboarding(ctx context.Context, agentID, creatorID uuid.UUID) (*OnboardingResponse, error)

GetAgentOnboarding 查询创作者侧接入完成度、能力声明和 examples。

func (*Service) GetBrowserInteractionPolicy added in v0.1.56 

func (s *Service) GetBrowserInteractionPolicy(
	ctx context.Context,
	agentID,
	ownerID uuid.UUID,
) (*BrowserInteractionPolicyResponse, error)

func (*Service) GetMyAgent 

func (s *Service) GetMyAgent(ctx context.Context, agentID, creatorID uuid.UUID) (*AgentResponse, error)

GetMyAgent 创作者按 id 查自己的 Agent（编辑前预填用）。

func (*Service) ListAvailabilityAlerts 

func (s *Service) ListAvailabilityAlerts(ctx context.Context, creatorID uuid.UUID, limit int32) (*AvailabilityAlertListResponse, error)

func (*Service) ListMyAgents 

func (s *Service) ListMyAgents(ctx context.Context, creatorID uuid.UUID) ([]AgentResponse, error)

ListMyAgents 创作者中心列表。

func (*Service) ListMyAgentsPage added in v0.1.14 

func (s *Service) ListMyAgentsPage(ctx context.Context, creatorID uuid.UUID, opts AgentListOptions) (*AgentListResponse, error)

func (*Service) ListPendingForAdmin 

func (s *Service) ListPendingForAdmin(ctx context.Context) ([]AgentResponse, error)

ListPendingForAdmin admin/运营人工处理队列。

func (*Service) MarkAvailabilityAlertRead 

func (s *Service) MarkAvailabilityAlertRead(ctx context.Context, creatorID, alertID uuid.UUID) (*AvailabilityAlertResponse, error)

func (*Service) RejectCertification 

func (s *Service) RejectCertification(ctx context.Context, agentID uuid.UUID, reason string) error

RejectCertification 运营拒绝认证申请。pending → rejected。

func (*Service) RequestCertification 

func (s *Service) RequestCertification(ctx context.Context, agentID, creatorID uuid.UUID) error

RequestCertification 创作者发起认证申请。unreviewed/rejected → pending。

func (*Service) RunDryRun 

func (s *Service) RunDryRun(ctx context.Context, agentID, creatorID uuid.UUID) (*DryRunResponse, error)

RunDryRun 用首条 example 的 input 调用创作者 endpoint，更新 onboarding 状态。

流程：

  1. 校验 Agent 归属（GetAgentByIDForOwner）
  2. 取首条 example.input_json
  3. 调 DryRunner（不计费；Runtime 通过持久化 Run 派发）
  4. 把结果写到 agent_onboarding_status.dry_run_*
  5. 返回 DryRunResponse

func (*Service) RunDueAvailabilityChecks 

func (s *Service) RunDueAvailabilityChecks(ctx context.Context, limit, staleSeconds int32) (*AvailabilityCheckBatchResponse, error)

RunDueAvailabilityChecks executes one monitor batch. It is exposed for tests and operational one-shot runs; regular production use should go through StartAvailabilityMonitor.

func (*Service) SetDryRunner 

func (s *Service) SetDryRunner(r DryRunner)

SetDryRunner 注入 endpoint 探活器；为 nil 时 RunDryRun 返回 503。

构造时不接收 DryRunner 是为了保留 main.go 中循环依赖的解耦点： agent 和 runtime 互不引用，必要时由 cmd/api/main.go 在两者都构造完成后串起来。

func (*Service) SetVisibility 

func (s *Service) SetVisibility(ctx context.Context, agentID, creatorID uuid.UUID, visibility string) (*AgentResponse, error)

SetVisibility 仅变更市场可见范围，避免客户端为了改状态而重传 endpoint 凭据。

func (*Service) UpdateAgent 

func (s *Service) UpdateAgent(ctx context.Context, agentID, creatorID uuid.UUID, req *UpdateAgentRequest) (*AgentResponse, error)

UpdateAgent 创作者编辑 Agent 基础信息（含 visibility）。

SQL 仅在 lifecycle_status='active' 且 creator_id 匹配时返回； RETURNING 命中 0 行 → pgx.ErrNoRows，service 层再用 GetAgentByIDForOwner 区分两种 case：

  • 不存在 / 不属于该 creator → NotFound
  • disabled → Forbidden

Visibility 空串视为不改（默认沿用旧值）；显式传值则按 public/unlisted/private 校验。

func (*Service) UpdateBrowserInteractionPolicy added in v0.1.56 

func (s *Service) UpdateBrowserInteractionPolicy(
	ctx context.Context,
	agentID, creatorID uuid.UUID,
	req *UpdateBrowserInteractionPolicyRequest,
) (*BrowserInteractionPolicyResponse, error)

func (*Service) UpsertCapability 

func (s *Service) UpsertCapability(ctx context.Context, agentID, creatorID uuid.UUID, req *UpsertCapabilityRequest) (*CapabilityResponse, error)

UpsertCapability 保存 Agent input/output JSON Schema。

type SkillMini 

type SkillMini struct {
	ID          string `json:"id"`
	Category    string `json:"category"`
	Name        string `json:"name"`
	Description string `json:"description"`
}

SkillMini 详情页公开展示的 Agent skill。

type SlugCheckResponse 

type SlugCheckResponse struct {
	Slug      string `json:"slug"`
	Available bool   `json:"available"`
}

SlugCheckResponse GET /agents/check-slug 响应。

type UpdateAgentRequest 

type UpdateAgentRequest struct {
	Name               string   `json:"name" validate:"required,min=3,max=80"`
	Description        string   `json:"description" validate:"max=500"`
	EndpointURL        string   `json:"endpoint_url" validate:"max=500"`
	EndpointAuthHeader string   `json:"endpoint_auth_header" validate:"max=500"`
	ClearEndpointAuth  bool     `json:"clear_endpoint_auth_header"`
	PricePerCallCents  int32    `json:"price_per_call_cents" validate:"min=0,max=1000000"`
	Tags               []string `json:"tags" validate:"required,min=1,max=5,dive,min=2,max=30"`
	Visibility         string   `json:"visibility" validate:"omitempty,oneof=public unlisted private"`
	ConnectionMode     string   `json:"connection_mode" validate:"omitempty,oneof=direct_http mcp_server runtime"`
	MCPToolName        string   `json:"mcp_tool_name" validate:"omitempty,min=1,max=120"`
}

UpdateAgentRequest 编辑 Agent 请求体。slug 不可改。 Visibility 可空字符串视为不改，否则只接受 public / unlisted / private。

type UpdateBrowserInteractionPolicyRequest added in v0.1.56 

type UpdateBrowserInteractionPolicyRequest struct {
	InteractionPolicy      string   `json:"browser_interaction_policy" validate:"required,oneof=restricted full"`
	BrowserMutationOrigins []string `json:"browser_mutation_origins" validate:"max=32,dive,required,max=500"`
}

UpdateBrowserInteractionPolicyRequest changes durable Browser authority. Origins are canonicalized by Core; callers cannot provide a digest or generation and therefore cannot widen or replay the trusted lease tuple.

type UpdateVisibilityRequest 

type UpdateVisibilityRequest struct {
	Visibility string `json:"visibility" validate:"required,oneof=public unlisted private"`
}

UpdateVisibilityRequest 仅切换市场可见性，不要求重传 endpoint 鉴权等敏感配置。

type UpsertCapabilityRequest 

type UpsertCapabilityRequest struct {
	InputSchema  map[string]interface{} `json:"input_schema" validate:"required"`
	OutputSchema map[string]interface{} `json:"output_schema" validate:"required"`
	Summary      string                 `json:"summary" validate:"max=1000"`
}

UpsertCapabilityRequest 保存 Agent 能力声明。

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.